By Partly fixable yourself. Often a missing setting on the host, not code.
- How serious
- High
- Fix it yourself?
- Partly, some steps need a developer
- Typical cost
- $49–$800 one-off check, or €99–$990 for a single fix (prices)
- Top rated for Cursor
- Afterbuild Labs · 10.0/10
What you see. Everything runs on localhost, but the deployed version shows errors, empty data, or a failed build.
Why it happens
Your laptop has things the server does not. The biggest one is the .env file. Next.js loads variables from .env files on your machine, but the default template adds those files to .gitignore, so they never reach the host. On Vercel, values live in the project's Environment Variables settings, and a change there only applies to new deployments. Variables meant for the browser need the NEXT_PUBLIC_ prefix and are frozen into the code at build time.
Second, the dev server is forgiving. next dev skips checks that next build enforces, so type errors and missing imports only surface on the server. Third, versions differ. Vercel builds with the latest Node.js LTS by default unless your package.json engines field says otherwise. Fourth, the code may point at localhost or a local database the server cannot reach. Coding agents like Cursor and Claude Code write such paths without telling you.
Fix it yourself
- Open the failed deployment in Vercel and read the build log down to the first red line. Copy the exact error text before changing anything.
- Run
npm run buildon your laptop. If it fails the same way, the problem is in the code, not the host. - Compare your
.env.localfile with Project → Settings → Environment Variables in Vercel. Add every missing name and value, tick the Production environment, then redeploy. - Search the code for
localhost,127.0.0.1, and hardcoded file paths. Replace them with environment variables. - Check Settings → Build and Deployment → Node.js Version in Vercel and match it to
node -von your laptop, or setengines.nodeinpackage.json. - Ask the agent to fix only the first error from the log, redeploy, and repeat. Do not ask it to fix the deployment in general.
When to get an engineer
Stop when the environment variables are in place and the build still fails, or when the build passes but pages crash with errors you cannot read. Give the engineer the build log, the list of variable names (never the values), and the repository link. Expect a one-off check at $49–$800 or a single fix at €99–$990, usually within 1–2 days. The deep page works on localhost, breaks in production covers the agent-specific traps.
Top-rated companies for Cursor apps
Ranked by our score: published prices, scope of work, AI tools named, timing and a low-risk first step. How we score.
- 1Afterbuild Labs10.0/10Best for: A check before launchFree first step · from $49
- 2Redlab10.0/10Best for: A full rescue by one team that keeps buildingFree first step · from $490
- 3Vibe Code Rescue (Lev Arakelyan)9.0/10Best for: A one-off check and a cleanupFrom $299
Check these
Secrets live in the host's environment settings
Keys belong in environment variables on the server, not in the repository or in front-end code.
The code lives in a Git repository you own
Connect GitHub or export the project. If the builder account is lost, the product should not be.
Testing and real users use separate databases
Experiments and AI agents should never run against production data.
Errors reach you before users do
Add error monitoring and uptime alerts. If you learn about outages from customers, this is missing.
Questions
Why does my .env file not work on Vercel?
It never left your laptop. The file is ignored by Git, so the host never sees it. Vercel reads values only from the project's Environment Variables settings, and only for deployments made after you add them.
Can I just copy the .env file into the repository?
No. That publishes your secret keys to everyone with repository access. Add each value in the host's settings instead, and keep the file out of Git.
Sources: Vercel: Environment variables; Vercel: Managing environment variables; Next.js: Environment variables guide; Vercel: Supported Node.js versions.