Fix Common Netlify Build Errors: Exit Code 1, Module Not Found, and More

Build failures are the worst. Everything works on your machine, you push to GitHub, Netlify picks it up… and then it dies with some cryptic error message. I've been there more times than I'd like to admit.

The good news is that most Netlify build errors fall into a handful of categories. Once you learn to read the build log (and know where to look), fixing them becomes a lot less painful.

How Netlify builds work

Every deploy follows this sequence:

1. Clone your Git repo
2. Install dependencies
3. Run your build command
4. Publish the output directory

If something goes wrong in step 2 or 3, the deploy fails. The key to debugging is figuring out which step broke — the error messages are usually pretty clear about this if you know where to look.

Reading the build log

When a build fails, click the failed deploy in the Netlify dashboard and open the Deploy log. Don't scroll randomly — start from the top and scan down until you see:

• A red error message
• A stack trace
• A command that exited with a non-zero status

That section tells you what went wrong. Everything above it is just noise (dependency installation, build setup, etc.).

The most common errors

Dependency install failures

What you'll see: Errors mentioning npm install, yarn install, or pnpm install. Messages like Cannot find module or ERESOLVE unable to resolve dependency tree.

What's usually wrong:

• Your lockfile doesn't match your package manager (e.g., yarn.lock in a project using npm)
• The lockfile is out of date or corrupted
• A dependency was removed but the lockfile wasn't updated

Fix it:

• Commit the right lockfile — package-lock.json for npm, yarn.lock for yarn, pnpm-lock.yaml for pnpm
• Only use one package manager per project
• When in doubt: delete node_modules, delete the lockfile, reinstall, and commit the fresh lockfile

Wrong Node.js version

What you'll see: SyntaxError: Unexpected token on code that definitely works locally. Or warnings about unsupported Node versions.

Fix it: Tell Netlify which Node version to use. In netlify.toml:

[build]
  node_version = "18"

Or create an .nvmrc file in your project root:

18

Netlify respects both. I'd recommend matching whatever version you use locally.

"Works on my machine" syndrome

What you'll see: Build passes locally, fails on Netlify. No obvious error.

What's usually wrong:

• Missing environment variables (you have them locally but didn't add them to the Netlify dashboard)
• Case-sensitive file paths (macOS is case-insensitive, Linux isn't — and Netlify runs on Linux)
• Globally installed tools that aren't in your package.json

Fix it:

• Double-check env vars in Site settings > Environment variables
• Fix import paths to match exact casing: import Header from './header' will fail if the file is Header.tsx
• Add any tools you rely on (like sharp, sass, etc.) to your package.json

The case sensitivity thing bites macOS developers constantly. You rename header.tsx to Header.tsx, Git doesn't notice the change (because macOS treats them as the same file), and Netlify can't find the module.

Missing environment variables

What you'll see: Crashes during data fetching, "API key is required" errors, or just blank content where dynamic data should be.

Fix it: Add the variables in Site settings > Environment variables. If you need different values for production vs. previews, use the deploy context dropdown.

Don't forget to redeploy after adding them — they don't take effect until the next build.

Wrong publish directory

What you'll see: Build succeeds (green checkmark!) but the site shows a 404 or "Page not found." Or you see Deploy directory does not exist.

Fix it: Make sure the publish directory in your build settings matches what your framework actually outputs:

• Next.js: .next
• Gatsby: public
• Astro: dist
• Vite/React: dist
• Hugo: public

Update netlify.toml:

[build]
  command = "npm run build"
  publish = "dist"

Monorepo path issues

What you'll see: Netlify can't find package.json, or the build runs in the wrong directory entirely.

Fix it: Set a base directory:

[build]
  base = "apps/web"
  command = "npm run build"
  publish = "dist"

Framework adapter problems

What you'll see: Unexpected errors from Next.js, Astro, or SvelteKit that don't happen locally. References to missing adapters or incompatible runtimes.

Fix it:

• Make sure you're using the official Netlify adapter for your framework
• Check that the adapter version is compatible with your framework version
• Keep adapters up to date — they tend to lag behind framework releases

Reproducing the build locally

The Netlify CLI can run the build the same way Netlify's servers do:

npm install -g netlify-cli
netlify build

This catches issues that npm run build alone might miss — things like missing env vars, wrong Node versions, or publish directory mismatches.

When you're stuck

If you've been staring at the build log for 20 minutes and nothing makes sense:

• Compare with a working deploy — click an older successful deploy and diff the logs
• Check recent dependency changes — package.json diffs are a common culprit
• Google the exact error message — Netlify errors are very googleable, and the community forums usually have answers
• Try a clean build — in the Netlify dashboard, go to Deploys > Trigger deploy > Clear cache and deploy site

Build errors feel intimidating, but 90% of the time it's one of the issues above. Read the log, fix one thing at a time, and you'll get there.