GUIDES · ENVIRONMENT VARIABLES

process.env is undefined on Vercel: how to find the missing variable

Your env variable works locally and is undefined on Vercel. Where Vercel reads variables from, why NEXT_PUBLIC values need a rebuild, and how to list what your code expects.

Where Vercel reads variables from

A local .env.local file is normally gitignored and is not present in a clean deployment. Configure secrets in Vercel project settings, scoped to Production, Preview or Development. Frameworks may also load committed .env files; never commit secrets to make a deployment work. A variable added for Production only is undefined in every Preview deployment.

NEXT_PUBLIC variables are inlined at build time

Anything prefixed NEXT_PUBLIC_ is replaced in the client bundle when next build runs. Adding the variable after the build and redeploying from cache keeps the old undefined value. Use Redeploy without build cache, or push a commit.

Module scope throws kill the whole build

A client created at module scope, for example new Stripe(process.env.STRIPE_SECRET_KEY), runs during the build for every statically rendered page. When the key is missing the build fails with a stack trace that points at the SDK, not at the variable. Wrap such clients in a function and create them lazily inside the request handler.

let client: Stripe | undefined;
export function stripe() {
  const key = process.env.STRIPE_SECRET_KEY;
  if (!key) throw new Error("STRIPE_SECRET_KEY is not set");
  return (client ??= new Stripe(key));
}

List what your code expects

Search the repository for process.env. and compare the names against .env.example and against the Vercel project. DeployDoctor does that diff from the repo URL and lists every variable the code reads that .env.example does not document.

Error reference: What it means

Environment variables are key-value pairs configured outside your source code. Vercel applies each one to the environments you select: Production, Preview, Development or a custom environment. Your code reads them during the Build step or during function execution.

Any change to an environment variable is not applied to previous deployments. It only applies to new deployments.

Error reference: How to fix it

1. List every process.env value your code reads and compare it with the variables in the project settings.

2. Add each missing variable under Environment Variables for every environment you deploy to. Production applies to the next Production deployment. Preview applies to deployments from branches other than the Production Branch.

3. Redeploy. The new value is not applied to a deployment that already exists.

4. To use the same values locally, run vercel env pull. It writes the Development variables to a .env file.

5. In Next.js, a variable without the NEXT_PUBLIC_ prefix is only available on the server. A NEXT_PUBLIC_ variable is inlined into the JavaScript bundle at build time, so changing it requires a new build.

Error reference: Limits to know

A deployment can use 64 KB of environment variables in total. Functions and Middleware that use the edge runtime are limited to 5 KB per variable.

What the repository scan cannot verify

The environment variable check reports process.env reads that are not documented in .env.example, secret-looking values exposed through NEXT_PUBLIC_, and an .env.example that .gitignore keeps out of the repository. A scan reads the repository only. It cannot see the values or names saved in your Vercel project settings.

Sources

Updated 2026-11-15