← All errors · VercelVercel build & deploy errors

Works locally but fails on Vercel

Exact error

Build or runtime succeeds on localhost but fails after deploying to Vercel

What it means

Something differs between your machine and Vercel's build environment.

Likely causes

• Env vars in .env.local that are not added to Vercel.
• Case-insensitive filesystem locally (macOS/Windows) vs case-sensitive Linux on Vercel.
• Different Node.js version.
• Files ignored by git (.gitignore) that exist only on your machine.

How to fix it

1. Compare env vars: Vercel Project → Settings → Environment Variables. You can pull them to check:

   vercel env pull .env.vercel

2. Set the Node version explicitly:

   // package.json
   "engines": { "node": "20.x" }

3. Run `git status` and check required files are actually committed.

4. Run `npm ci && npm run build` locally to mimic a clean build.

Prevent this next time

• Add a CI job that runs `npm ci && npm run build` on every push, mirroring a clean Vercel build.
• Pin your Node.js version in package.json `engines` and commit your lockfile.

Guide: catch outages before your users do.

Related errors

• Command "npm run build" exited with 1
• Environment variable is undefined in the browser
• Module not found: Can't resolve '...'