Vercel Env Checker

Next.js / Vercel env debug wizard

Debug missing Vercel environment variables.

Find why a Next.js env variable is undefined, stale, or missing in production. Get a prioritized checklist, safe commands, and a debug snippet that does not print secret values.

Describe the failure

No secrets needed
Do not paste API keys, tokens, passwords, database URLs, or real environment variable values into this tool.

Most likely causes

critical

The browser cannot read a server-only variable

Next.js does not expose non-public environment variables to browser code.

  • Do not add NEXT_PUBLIC_ to a secret. Move the read to an API route, route handler, server component, or backend service.
  • Confirm the failing code is really running in the browser.
warning

The value may be configured in the wrong Vercel environment

Vercel has separate Production, Preview, and Development environment scopes.

  • Open Vercel Project Settings > Environment Variables.
  • Confirm the value exists for Production deployment.
  • If the value was added after the deployment, redeploy the target environment.

Safe commands

vercel env ls
vercel env pull .env.local
vercel --prod

Safe debug snippet

const value = process.env.MY_ENV_VAR;

console.log({
  name: "MY_ENV_VAR",
  exists: Boolean(value),
  length: value?.length ?? 0,
});

// Do not log the raw value.

What this checks

The checker covers common Next.js and Vercel environment variable mistakes: browser access, `NEXT_PUBLIC_`, production versus preview scope, redeploy timing, local sync, and safe debugging.

What this does not do

It does not connect to your Vercel account, inspect your repository, read secret values, or guarantee that a deployment is production-ready.

Official references

Next.js environment variablesVercel environment variables

Related checks

Docker ComposeEnv interpolation checker

Find missing ${VAR} names, defaults, required markers, and env_file boundaries.

GitHub ActionsReusable workflow env checker

Compare workflow_call inputs and secrets with the caller mapping.

GitHub ActionsToken permissions preflight

Check GITHUB_TOKEN scopes for PR comments, releases, checks, packages, and Pages deploys.

GitHub ActionsUpload artifact preflight

Check hidden files, path patterns, overwrite, compression, and retention before artifacts go missing.

Next.js ImageRemote patterns preflight

Diff an image URL against remotePatterns before the Invalid src prop error reaches deploy.

PlaywrightwebServer baseURL preflight

Catch server URL, baseURL, port, timeout, and reuseExistingServer drift before E2E tests hang.

PlaywrightProject dependency preview

Preview setup, dependency, teardown, UI-mode, and no-deps execution boundaries without running tests.

TerraformTfvars variable preflight

Compare variable declarations with tfvars assignment names before a plan run.

PydanticSettings env preflight

Compare BaseSettings fields with env names and v2 import boundaries.

Auth.jsTrusted host env preflight

Check AUTH_SECRET, AUTH_TRUST_HOST, callback URLs, and legacy NEXTAUTH names.

dbtProfiles target preflight

Compare dbt_project profile names with profiles.yml targets and env_var references.

Vitestjsdom environment preflight

Check jsdom, happy-dom, setupFiles, globals, and DOM test error clues before Vitest runs.

ViteEnv prefix preflight

Check import.meta.env references, VITE_ exposure, and public secret-like names.

ViteBase path preflight

Check base, GitHub Pages subpaths, public asset URLs, and router basename clues.

Common cases

Why is my variable undefined in the browser?

In Next.js, browser-exposed values need the `NEXT_PUBLIC_` prefix. Do not use that prefix for secrets.

Why do I still see the old value?

Public client values are bundled at build time. Change the value, create a new deployment, and confirm production points to it.

Why does local work but Vercel fails?

Your local `.env.local` and Vercel project environments may not match. Pull Vercel env values locally and restart the dev server.