fix guide
Command "npm run build" exited with 1 on Vercel
Harjot · · updated
Your app was built with Lovable, Bolt, Cursor or v0, and it runs on your machine. Then the Vercel deployment stops with Command "npm run build" exited with 1. That line only says the build command failed. The cause sits in the lines above it.
Vercel's docs say the last red error line often does not name the real problem. Scroll up to the error that names a file and a line number, then work through the six steps in order. If the build passes and the live site shows a 404 on refresh, that is a routing setting, covered in /guides/404-on-refresh-vercel.
1. Find the real error above the exit line
Open the failed deployment in the Vercel dashboard. Expand the Building accordion under Deployment Details, then scroll through the red lines. Look a few lines above the exit line for the error that names a file, a module or a line number.
Run the same build on your own machine, in the project folder:
npm run buildIf the same error shows up locally, fix it there first. Vercel's docs recommend building locally before you deploy.
signs The log has a red error line above the exit line that names a file and a line number.
2. TypeScript errors
Next.js fails next build when it finds TypeScript errors, so one type error stops the whole deployment.
Run this in the project folder to list every type error with its file and line:
npx tsc --noEmitFix each error it lists. The Next.js docs say the typescript.ignoreBuildErrors option skips the type check entirely and can be dangerous. Leave it off.
signs The log names a file and a TypeScript message, such as Type 'string' is not assignable to type 'number'.
3. Import paths with the wrong letter case
Vercel's build image runs Amazon Linux 2023, which is Linux. Linux file names are case-sensitive, so ./Button and ./button point to different files.
Your Mac or Windows PC ignores letter case by default. The import works locally and fails on Vercel.
Find the exact file name in your repo:
git ls-files | grep -i buttonChange the import so its capitals match the file name exactly. Then commit and push.
signs The log says Module not found: Can't resolve and shows a path whose capitals differ from the file in your project.
4. Environment variables missing at build time
Vercel saves each variable per environment: Production, Preview or Development. A variable set only for Preview is missing from a Production build.
Open Settings, then Environment Variables. Check that every variable your build reads is set for the environment that failed.
Next.js inlines NEXT_PUBLIC_ variables into the JavaScript when next build runs. Vite does the same with VITE_ variables. Vercel applies a change only to new deployments, so after you add or change one, push a new commit to run the build again.
Keep secrets out of these prefixed names. Their values end up in JavaScript that the browser downloads.
For the general version of this problem, see Environment variable undefined in production on Vercel.
signs The log shows an error about a missing or undefined value, and that variable is not set for the environment that failed.
5. A package is used but not listed in package.json
Vercel installs your dependencies from package.json before it builds. If your code imports a package that package.json does not list, the build can fail on Vercel even when it works on your machine.
Check where the package comes from. Replace the placeholder with the package name:
npm ls <pkg>If the package is missing from package.json, add it:
npm install <pkg>Vercel installs devDependencies too, unless you change the Install Command to skip them. A build tool such as typescript can stay in devDependencies. Commit package.json and the lockfile together.
signs The log says Module not found for a package name such as zod, and that name is not in package.json.
6. Node.js version does not match
Vercel builds with the Node.js version in Project Settings. Open Settings, then Build and Deployment, then the Node.js Version section. The default is 24.x, and 22.x is also available.
Check the version on your machine:
node -vYou can also set the version in package.json. A value in engines.node overrides the Project Settings choice:
{ "engines": { "node": "24.x" } }signs Your local node -v shows a different major version from the Node.js Version in Project Settings.
Test it like a new user
- Run npm run build on your machine and confirm it finishes with no error.
- Run npx tsc --noEmit and confirm it prints no errors.
- Push a commit and open the new deployment's Building log. Check for no red error lines.
- Open the live site and check that a page using a NEXT_PUBLIC_ or VITE_ value shows it.
- In Project Settings, confirm the Node.js Version matches the major version from node -v on your machine.
Common questions
What does npm run build exited with 1 mean on Vercel?
It only means the build command failed. The real error sits in the lines above it in the build log. Scroll up to the first error that names a file, a module or a line number, then run npm run build on your own machine to see it.
Why does my app build locally but fail on Vercel?
Vercel builds on Linux, from a clean install, with its own settings. The usual causes are TypeScript errors, imports with the wrong letter case, environment variables not set for that environment, packages missing from package.json, and a different Node.js version.
Should I turn on ignoreBuildErrors to make my Vercel build pass?
No. It skips the TypeScript check entirely, and the Next.js docs say that can be dangerous. Run npx tsc --noEmit in the project folder to list every type error with its file and line, then fix each one and push again.
Still stuck?
Not sure this is the cause? Paste your app's link into the free scan. It lists what a visitor's browser can see, like leaked keys and exposed files, worst first. The score is free; every fix as a prompt for your builder is $9, one-time.
Want a person to look inside? See the diagnosis