Vercel · Deployment guide
Vercel “Environment Variable not found” errors
Short answer
Vercel scopes env vars to Production, Preview and Development separately. Most “not found” errors are environment-scope mismatches, missing NEXT_PUBLIC_ prefixes, or a build-time variable that wasn't set before the build started.
Symptoms
- Build log: “Environment Variable X references Secret Y, which does not exist.”
- Runtime: “process.env.X is undefined” only on Preview deploys.
- NEXT_PUBLIC_ variables show as undefined in the browser.
- Works on Production but breaks on every Preview from a PR.
Common causes
- Variable set for Production only, not Preview (Vercel scopes are independent).
- NEXT_PUBLIC_ prefix missing — Next.js only inlines variables with that prefix into the client bundle.
- Variable was added after the build started — Vercel snapshots env vars at build time.
- Edge runtime can't read certain Node-only env access patterns.
- Variable name has a typo or wrong case (env names are case-sensitive).
How DeployDoc checks this
- Reads Vercel project env vars per environment and diffs against code references.
- Flags every NEXT_PUBLIC_ leak that bundles a server secret into the browser.
- Catches build-time vs runtime mismatches in App Router and Pages Router.
- Verifies edge-runtime functions don't reference Node-only env shapes.
Fix it manually
- Open Vercel → Project → Settings → Environment Variables.
- For each variable, check the box for Production, Preview, Development as needed.
- Server secrets: no
NEXT_PUBLIC_prefix. Client values: must have it. - Redeploy from scratch (don't just promote a previous build).
- Verify in the build log: Vercel prints “Loaded N env variables from project settings”.
When to run a DeployDoc diagnosis
Any time a Vercel deploy fails with an env error or behaves differently across Production and Preview. Connect Vercel in DeployDoc for one-click env audits.