A Next.js app that works locally returns 500 on Vercel
500 Internal Server ErrorShort answer
A 500 on Vercel means a server function threw an error. Read the runtime logs for the failing request to see the real message. The usual cause is an environment variable that is missing, scoped to the wrong environment, or added after the deployment was built. Set it for the right environment and redeploy.
Fix it fast
1Find out which cause you have
Read the runtime error for the failing deployment and request. The message names the variable or line that failed; the causes below are what that message usually turns out to be.
vercel logs runtime --environment production --query 'level:error' --since 1h2Match what you see, then jump to its fix
- 1
The error mentions undefined, a missing key or a failed connection string, and only on Production or only on PreviewThe variable is not set for the environment that served the requestFix - 2
The variable shows in the dashboard, but the same 500 continues on the existing deploymentThe variable was added after the deployment was builtFix - 3
The error appears in client components, or a NEXT_PUBLIC_ value is undefinedA server-only variable is read in code that runs in the browser, or a dynamic lookup is usedFix - 4
The 500 comes from a route under /api/auth or from a page that calls auth()Auth.js (NextAuth) has no secret in productionFix
- 1
What does the error look like?
500 Internal Server ErrorWorks locally with next dev, fails after deploy
Cause 1 of 4
The variable is not set for the environment that served the request
1Check
A .env.local file stays on your machine and is not uploaded. In the project settings, open Environment Variables and check that each name exists and that its Production, Preview and Development boxes match the deployment that fails.
vercel env list2Fix
Add the variable for the environment that fails. Values entered for Production do not apply to Preview deployments, and the reverse.
vercel env add DATABASE_URL --environment production
vercel env add DATABASE_URL --environment preview3Verify
Redeploy and open the page that returned 500.
vercel --prodConfirmed by vercel.com
Cause 2 of 4
The variable was added after the deployment was built
1Check
Vercel applies a changed variable only to new deployments. The running deployment keeps the values it had when it was created.
vercel env list --environment production2Fix
Create a new deployment: redeploy from the dashboard, push a commit, or run vercel --prod.
vercel --prod3Verify
Request the page again and watch the logs for a new, successful invocation.
vercel logs runtime --since 10mConfirmed by vercel.com
Cause 3 of 4
A server-only variable is read in code that runs in the browser, or a dynamic lookup is used
1Check
Only variables that start with NEXT_PUBLIC_ reach the browser, and Next.js replaces them at build time. A lookup such as process.env[name] is not replaced.
grep -rn "process.env\[" app src 2>/dev/null2Fix
Reference the full name in code (process.env.NEXT_PUBLIC_API_URL), keep secrets in server code only, and rebuild so the value is inlined.
// client code: a literal name is replaced at build time
const api = process.env.NEXT_PUBLIC_API_URL;3Verify
Redeploy and check the value in the browser.
vercel --prodConfirmed by nextjs.org
Cause 4 of 4
Auth.js (NextAuth) has no secret in production
1Check
The Auth.js docs list AUTH_SECRET as the one strictly required production variable. It needs at least 32 random characters. Provider values use the AUTH_<PROVIDER>_ID and AUTH_<PROVIDER>_SECRET names.
vercel env list | grep -i AUTH_2Fix
Generate a secret, add it with your provider credentials to the deployment's environment, and register the provider callback URL for your domain (default /api/auth/callback/<provider>).
npm exec auth secret
vercel env add AUTH_SECRET --environment production3Verify
Redeploy, then start a sign-in from the live domain.
vercel --prodConfirmed by authjs.dev
How do I stop it coming back?
- Keep a .env.example in the repository listing every variable the app reads, and compare it with the Vercel project before each release.
- Check each variable's environment boxes (Production, Preview, Development) when you add it.
- Redeploy after any variable change, and never assume the old deployment picked it up.
- Read the runtime logs first on any 500 instead of guessing from the browser.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix