Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A Next.js app that works locally returns 500 on Vercel

Error500 Internal Server Error

Short 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.

  • Applies to Next.js 15, Vercel CLI, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 1h
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The variable shows in the dashboard, but the same 500 continues on the existing deploymentThe variable was added after the deployment was builtFix
    3. 3The 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. 4The 500 comes from a route under /api/auth or from a page that calls auth()Auth.js (NextAuth) has no secret in productionFix

What does the error look like?

  • 500 Internal Server Error
  • Works 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 list

2Fix

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 preview

3Verify

Redeploy and open the page that returned 500.

vercel --prod

Confirmed by vercel.com

Did this fix it?

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 production

2Fix

Create a new deployment: redeploy from the dashboard, push a commit, or run vercel --prod.

vercel --prod

3Verify

Request the page again and watch the logs for a new, successful invocation.

vercel logs runtime --since 10m

Confirmed by vercel.com

Did this fix it?

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/null

2Fix

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 --prod

Confirmed by nextjs.org

Did this fix it?

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 production

3Verify

Redeploy, then start a sign-in from the live domain.

vercel --prod

Confirmed by authjs.dev

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.