Netlify · Deployment guide
Netlify deploy failed: missing environment variables
Short answer
Netlify has two axes of scope: deploy contexts (Production / Deploy Previews / Branch) and access scopes (Builds / Functions / Runtime). Most “env not found” failures are a mismatch on one axis.
Symptoms
- Build log says “env variable X required but not defined”.
- Production builds pass but Deploy Previews fail.
- Functions throw “process.env.X is undefined” at runtime.
- Variable shows in the Netlify UI but not in build output.
Common causes
- Variable is scoped to Production only, missing for Deploy Previews / Branch Deploys.
- Variable scope is set to Builds only — Functions can't read it at runtime.
- netlify.toml [build.environment] overrides the UI value for that context.
- Variable name has a leading/trailing space when pasted into the UI.
- Sensitive flag is on, but the value was never re-entered after enabling it.
How DeployDoc checks this
- Reads Netlify env settings per context and per scope, diffs against code references.
- Flags netlify.toml overrides that silently shadow the dashboard value.
- Catches function-scope omissions — a variable that builds need but functions don't see.
- Detects sensitive-flag empties (var name exists, value is blank).
Fix it manually
- Open Netlify → Site → Environment variables.
- For each variable, set Scopes to include Functions if any function uses it.
- Set Deploy contexts to All (or explicitly add Deploy Previews + Branch deploys).
- Search netlify.toml for
[build.environment]— values there override the UI. - Trigger a fresh deploy (clear cache and deploy) and watch the build log.
When to run a DeployDoc diagnosis
Whenever a Netlify build fails after working locally, or a function returns 500 after a successful deploy. DeployDoc parses your netlify.toml plus the build log in one pass.