You push to your repo and Netlify shows:

Build failed

Or in the deploy log:

"build.command" failed

Your site didn’t deploy, and the error message alone doesn’t tell you much.

What causes this

Netlify runs your build command in a containerized environment. The build can fail for many reasons, and the root cause is almost always in the deploy logs — not the summary.

Common causes:

• Your build command or publish directory is wrong in netlify.toml or the Netlify UI
• A dependency fails to install (Node.js version mismatch, missing native dependencies)
• Your code has build errors that don’t show up locally (different Node version, missing env vars)
• You’re running out of memory during the build (common with large sites)
• Environment variables needed at build time aren’t configured

Fix 1: Read the actual build logs

The “Build failed” message is just the summary. The real error is in the logs:

1. Go to Netlify → your site → Deploys
2. Click the failed deploy
3. Scroll through the build log — the error is usually near the bottom

Look for lines starting with Error:, ERR!, or FATAL. The log shows every command Netlify runs, so you can see exactly where it breaks.

Fix 2: Set the correct build command and publish directory

The most common misconfiguration. Make sure your netlify.toml matches your framework:

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

Common publish directories by framework:

• Astro: dist
• Next.js: .next (or out for static export)
• Vite/React: dist
• Gatsby: public
• Hugo: public

If you set the build config in both netlify.toml and the Netlify UI, the netlify.toml takes precedence.

Fix 3: Pin your Node.js version

Netlify’s default Node.js version may not match what you use locally. Pin it:

# netlify.toml
[build.environment]
  NODE_VERSION = "18"

Or use a .node-version or .nvmrc file in your repo root:

18

If your project uses features from Node 18+ but Netlify defaults to 16, you’ll get cryptic build errors.

Fix 4: Add missing environment variables

If your build depends on API keys, database URLs, or other secrets, they must be configured in Netlify:

Go to Site Settings → Environment Variables → Add a variable.

You can also set them in netlify.toml for non-sensitive values:

[build.environment]
  NEXT_PUBLIC_API_URL = "https://api.example.com"

Never put secrets in netlify.toml — that file is committed to your repo.

Fix 5: Test the build locally

Reproduce the Netlify build environment on your machine:

# Clean install, just like Netlify does
rm -rf node_modules
npm ci
npm run build

Use npm ci instead of npm install — that’s what Netlify runs. It installs from the lockfile exactly, which can surface dependency issues that npm install hides.

You can also use the Netlify CLI:

npx netlify-cli build

This simulates the Netlify build process locally, including environment variable injection.

How to prevent it

• Always test npm ci && npm run build locally before pushing
• Pin your Node.js version in netlify.toml or .nvmrc
• Keep netlify.toml in your repo so build config is version-controlled
• Set up deploy previews for pull requests — they catch build failures before they hit production
• Use Netlify’s build notifications (Slack, email) so you know immediately when a deploy fails