Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 37 ยท Projects and Practice

Practice: Debugging Failed Deploys

A practical troubleshooting guide: read build logs, fix missing dependencies, Node versions, case-sensitive paths, environment variables, function errors, 404s and 5xx responses, plus a log classifier.

Every developer meets the red "Build failed" label sooner or later. The good news: failures follow a small number of patterns, and the platform tells you what happened in the build log and function logs. This lesson gives you a systematic method and a collection of the most common causes, followed by practice scenarios.

The platforms cannot run here, so there are no real logs. The messages shown are typical wording of the underlying tools (npm, Node, bundlers); platforms phrase their own lines differently. The runnable code is a JavaScript stand-in that classifies log text and explains it, which is a good way to learn the patterns.

A method, not a guess

  1. Find the first error. Scroll to the first line that says error or a non-zero exit code. Later lines are often consequences.
  2. Reproduce locally with the same commands and versions: npm ci && npm run build (use a clean install, not your cached node_modules).
  3. Compare environments: Node version, package manager, environment variables, operating system.
  4. Change one thing, push to a branch, read the preview's log.
  5. Roll back production first if it is live and broken (Rollbacks and Promotions); debug second.

Debug loop

First error Read the log from the top.
Reproduce Clean install and build locally.
Compare Versions, variables, OS.
One change Test on a preview.

Restore service before you investigate.

1 / 2

Build failures: the usual suspects

Symptom in the log Likely cause Fix
Cannot find module 'x' or Module not found package in devDependencies only used at runtime, missing from package.json, or wrong path install it as a dependency; check the import path
Path works on your laptop, fails on the server: Can't resolve './Header' case sensitivity: Windows and macOS ignore case, Linux build servers do not (header.js versus Header.js) match the exact case of file and import names
The engine "node" is incompatible or syntax errors in new language features Node version differs set the version in project settings, engines in package.json, or .nvmrc
npm ERR! ERESOLVE peer dependency conflicts dependency tree conflict fix versions; use the lockfile with npm ci; as a last resort --legacy-peer-deps
ENOENT: no such file or directory for the output directory wrong publish/output directory (dist vs build vs .next) correct the setting to match your tool
Command "build" not found or exit code 127 missing build script add it to package.json scripts
JavaScript heap out of memory build exceeds memory reduce work, raise memory with NODE_OPTIONS=--max-old-space-size=... if your plan allows, or upgrade
Warnings treated as errors Netlify sets CI=true, and some tools fail on lint warnings in CI fix the warnings, or set the tool's option deliberately
process.env.X is undefined variable not set for that environment add it for Production and Preview (Build Settings and Environments)
Build exceeds the time limit slow dependency install, huge asset pipeline cache dependencies, skip unneeded work, split the build

Runtime failures

A deployment can build fine and still fail for visitors:

  • 404 on page refresh in a single-page app: you need a fallback rewrite to index.html (Redirects and Rewrites).
  • 404 for an API route: the function file is in the wrong folder, or its name does not match the path.
  • 500 from a function: open function logs (Vercel: Logs tab, Netlify: Functions tab). Common causes are a missing environment variable, a failed database connection (Databases from Serverless), or an uncaught exception.
  • 502/504 or timeout: the function exceeded its time limit (Limits, Quotas and Costs); speed it up or move work to the background.
  • CORS errors in the browser console: the API response lacks Access-Control-Allow-Origin (Response Headers and Security).
  • Old content still showing: a cache; check headers and age (Caching and the CDN).
  • Mixed content or certificate warnings: HTTPS and Certificates.

A log classifier you can run

The stand-in below matches log lines against patterns and prints the likely cause and fix. Extend the rule list as you meet new failures: keeping your own runbook is genuinely useful.

JS Build log classifier stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practice scenarios

Read each scenario, decide the cause, then run the stand-in to check your reasoning.

1. The deploy works locally on macOS but fails with Can't resolve './Navbar'; the file is navbar.js. (Case sensitivity.)

2. The site loads but /dashboard returns the platform's 404 when you refresh the page. (Missing SPA fallback rewrite.)

3. Checkout works in production but the preview charges real cards. (Preview environment uses production keys.)

4. A function returns 500; the log says Cannot read properties of undefined (reading 'split') after you added a new setting. (Environment variable missing in this environment.)

5. After rolling back, a new merge does not go live. (Auto-publishing was paused by the rollback; re-enable it.)

JS Triage helper stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Prevent repeats

  • Run npm ci && npm run build in CI on every pull request so failures appear before the platform build.
  • Pin Node and the package manager; commit lockfiles.
  • Keep .env.example current and document which variables each environment needs.
  • Use preview deployments as the default place to find bugs.
  • After an incident, add the cause to your own runbook.

Where to look when stuck

  1. The build log's first error.
  2. Function logs and runtime logs for the failing request (note the request ID).
  3. The platform's status page: occasionally the platform itself has an incident.
  4. Documentation and community forums, searching for the exact error text.
  5. Support, with a deployment URL and the log excerpt, if you are on a plan that includes it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can an import work on Windows and macOS but fail in the platform build?

    Header.js and header.js are different files on Linux, so the import must match exactly.
  2. 2. What is the first step when reading a failed build log?

    One early failure can produce many later messages.
  3. 3. A page refresh on a client-routed app shows 404. What is the usual fix?

    The server must return index.html for unknown paths so the client router can handle them.
  4. 4. Production is broken right after a deploy. What should you do first?

    Restoring service quickly limits damage; the failed deployment remains available for analysis.

Summary

  • Debug systematically: first error, reproduce locally, compare environments, change one thing.
  • Common build failures: missing modules, case sensitivity, Node versions, dependency conflicts, wrong output directory, missing variables.
  • Common runtime failures: SPA 404s, function 500s and timeouts, CORS, caching, certificates.
  • Roll back first when production is affected.
  • Keep a runbook and catch problems early with CI and previews.

Next: Back to the Vercel and Netlify track