Playbook
Home / Vercel & Deploy / Roll back & debug

A deployment failed: read the build log

safe intermediate #build#logs#error#debug#failed

When to use this: Vercel shows 'Error' or 'Failed' on a deployment, and you need to find out why.

Before you start

Steps

  1. Open the failed deployment

    Project, Deployments, click the red row. The 'Build Logs' section holds the output. Scroll to the first Error line, since later lines are usually consequences.

  2. Reproduce it locally

    terminal
    npm ci
npm run build

    npm ci installs exactly from the lockfile, like Vercel does. If it fails locally too, fix it here, which is faster than redeploying.

  3. Check the common causes

    1) A missing environment variable. 2) File name case: Windows ignores case, Vercel's Linux builders do not (import './Header' vs header.astro). 3) A package only installed locally and missing from package.json. 4) Node version mismatch: set it in Settings, General, Node.js Version or in engines in package.json. 5) Wrong output directory.

  4. Fix, commit, push

    terminal
    git add -A
git commit -m "Fix build error"
git push

    Each push starts a new build.

  5. For runtime errors, read the live logs

    terminal
    vercel logs <deployment-url>

    Build logs cover the build. Errors that happen while visitors use the site show up in the project's 'Logs' tab or here.

How to verify it worked

  • The new deployment finishes with status Ready.

Common errors and fixes

Module not found: Can't resolve './Header' only on Vercel Case mismatch. Rename the file to match the import exactly. If Git did not notice the case-only rename, use git mv header.astro Header.astro.
ERR_PNPM_OUTDATED_LOCKFILE or npm ci complains package.json and the lockfile disagree. Run npm install locally and commit the updated lockfile.
Process exited with code 137 / out of memory The build ran out of memory. Reduce the build's memory use, or contact Vercel support for larger build resources if your plan allows.

Q&A

Why does it build on my PC but not on Vercel?

Different environment: case-sensitive files, missing environment variables, different Node version, or dependencies not declared in package.json.

Does a failed build take the site down?

No. Vercel keeps serving the previous successful Production deployment.

Practice these as flashcards →

Terms in this scenario

BuildPreview deployment

Related scenarios

My notes

Saved in this browser only.