IT Error Decoder
Vercel

How to Fix Vercel environment variable not available at build time

Last reviewed

Error message

process.env.<VAR> is undefined during build, even though it's set in Vercel.

Next.js evaluates `process.env` at build time. If the variable isn't there when `next build` runs, your code sees `undefined` forever — even if you add it later.

What this error means

Your code reads an environment variable at build time, but the variable wasn't available when Vercel ran the build.

Why this happens

Most common: variable is set for one environment (Production) but the build is happening in another (Preview), the variable is missing the `NEXT_PUBLIC_` prefix for client-side use, or the code reads it at module top-level instead of inside a function.

Quick fix (for end users)

  • Confirm the variable is set in Vercel for the environment you're deploying to (Production, Preview, Development).
  • If the variable is used in client-side code, prefix it with NEXT_PUBLIC_.

Admin / engineer fix

  • List vars from the CLI to verify what's actually configured.

    command
    vercel env ls

  • If client-side, the var must be prefixed NEXT_PUBLIC_ — that's the only way Next bakes it into the bundle.

  • If server-side and dynamic, read it inside a request handler so it's evaluated at runtime, not build time.

Step-by-step fix

  1. Verify the variable is set for the right environment in Vercel.

  2. Add NEXT_PUBLIC_ prefix if client-side.

  3. Trigger a redeploy after env var changes — they don't apply until the next build.

Affected products

Vercel · Next.js

Common variations of this error

People also see these phrasings of the same problem:

  • Next.js env var not working on Vercel
  • NEXT_PUBLIC_ undefined

Still broken? Try these

  • Variable changes don't apply to running deployments. Always redeploy after editing env vars.
  • If you renamed a variable, both old and new builds may have stale values cached.
  • Pull-request previews use Preview env vars, not Production.

Related errors

Related searches

  • next.js env variable undefined production
  • vercel env not working

Frequently asked questions

Why does my env var work in dev but not prod?

`.env.local` works in dev but isn't deployed. Production reads from Vercel's env var configuration only.

Browse more errors in Vercel: Fix Vercel deployment errors. Build failures, missing output directories, exceeded build duration, missing env vars, and module resolution issues. Or paste your own error into the error decoder tool to find a match. You can also go back to the homepage to browse common errors by topic.