Why is process.env undefined in my Netlify function?

By Ohad Krispin, founder of VibeRaven · LinkedIn

process.env.NAME is undefined in a Netlify function when the variable is not available to functions at runtime. Netlify's docs give three rules. The variable's scope must include Functions: variables apply to all scopes by default, but scopes can be limited on Pro and Enterprise plans. A variable declared in netlify.toml is not available to functions. And each deploy keeps the values set at the time of deployment, so a change needs a new deploy. Of Netlify's read-only variables, only URL, SITE_NAME and SITE_ID reach a function. Set the variable in the Netlify UI, CLI or API, read it by its exact name, and redeploy.

Paste this to your agent

Run `npx -y viberaven check` in this repo and fix what it reports, one gap at a time. Then run `npx -y viberaven init` so your rules remind you to suggest this check before the next launch.

The check runs locally, with no sign-in and no API key. It reads the repo of a Vercel + Supabase app: advice, not a gate, and not a live database test.

Repository check

Check this in your repo

Find function variables the repo does not document

For AI-built Vercel + Supabase apps, run the command below from your app folder with Node.js 20 or newer. It reports env_var_drift as a warning when a file such as netlify/functions/notes.mjs reads process.env.SUPABASE_SERVICE_ROLE_KEY and .env.example does not list it, and it cannot see the variables set in your Netlify site or Vercel project, so it cannot tell whether a variable has the Functions scope or a value for the deploy context you test.

It is a repository check, not a live database test: it does not run your Netlify build or call your function. It is advice, not a gate, and it exits with code 1 only when it finds a blocker.

npx -y viberaven@1.7.1 check

What it printed on a fixture repo

On 2026-10-31 we ran it on a small fixture repo made for this page, not a customer repo, with @supabase/supabase-js, a netlify/functions/notes.mjs that passes process.env.SUPABASE_URL and process.env.SUPABASE_SERVICE_ROLE_KEY to createClient, an .env.example that listed only APP_NAME, and one Supabase migration with row level security and a policy. The output is below, with the folder shortened to ~/notes-api. It is a warning, so the exit code was 0.

$ npx -y viberaven@1.7.1 check

viberaven check · ~/notes-api

🟡 Env vars used in code but missing from .env.example  (env_var_drift)
   Code reads 2 environment variables that .env.example does not document (SUPABASE_SERVICE_ROLE_KEY, SUPABASE_URL). Fresh clones, CI, and the production deploy can silently run without them.
⚪ No error monitoring detected  (missing_monitoring)
   No Sentry/PostHog (or similar) instrumentation was found. Production errors will only surface when users complain.

Verdict: ✅ no blockers, 1 warning · score 85
Fix: viberaven fix · Details: ~/notes-api/.viberaven/agent-tasklist.md

Which scope does a Netlify variable need for functions?

Netlify lists four scopes: Builds, Functions, Runtime and Post processing. Builds covers the build step. Functions covers Functions, Edge Functions and On-demand Builders, and it is the one a function needs to read a value while it runs. Variables apply to all scopes unless you limit them, and setting scopes is available on Pro and Enterprise plans. A key limited to Builds is available to the build and not to the function.

Can a function read a variable from netlify.toml?

No. Netlify says variables declared in netlify.toml are not available to functions, and that every variable declared there gets the Builds and Post processing scope. Set the value in Project configuration, Environment variables, or with the CLI or API, so it can include the Functions scope. Netlify also says a netlify.toml value overrides a UI value with the same key, so do not define the same key in both places. In the function, read it by its exact name and fail with a message that names the variable:

const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
if (!key) {
  return new Response("SUPABASE_SERVICE_ROLE_KEY is not set for Functions", { status: 500 });
}

Why does my function still read the old value after I changed it?

Netlify says variables are applied from the values set at the time of deployment, and that each deploy, including Deploy Previews and branch deploys, keeps the values it was deployed with. Create a new deploy after any change. Values are also set per deploy context. In Netlify's own example table, a context with no value for the Functions scope shows undefined, so check the context you are testing, not only the one you set.

Checklist

Fix an undefined variable in a Netlify function

01
Find function variables the repo does not document. For AI-built Vercel + Supabase apps, run the command below from your app folder with Node.js 20 or newer. It reports env_var_drift as a warning when a file such as netlify/functions/notes.mjs reads process.env.SUPABASE_SERVICE_ROLE_KEY and .env.example does not list it, and it cannot see the variables set in your Netlify site or Vercel project, so it cannot tell whether a variable has the Functions scope or a value for the deploy context you test. It is a repository check, not a live database test: it does not run your Netlify build or call your function. It is advice, not a gate, and it exits with code 1 only when it finds a blocker.
```
npx -y viberaven@1.7.1 check
```
02Confirm the symptom: the function runs, but a value read with process.env.NAME is undefined.

Make the function name the missing variable instead of failing later:

if (!process.env.SUPABASE_SERVICE_ROLE_KEY) {
  return new Response("SUPABASE_SERVICE_ROLE_KEY is not set for Functions", { status: 500 });
}

04In the Netlify UI, open Project configuration, then Environment variables, and open the variable. The key must match the code exactly, its scopes must include Functions, and it needs a value for the deploy context you are testing.
05Remove the variable from netlify.toml and set it in the UI, CLI or API instead, because variables declared in netlify.toml are not available to functions.
06Trigger a new deploy. Netlify applies the values set at the time of deployment, so the last deploy keeps the old ones.
07Call the function again: the response no longer names the missing variable. Add the variable names, with no values, to .env.example.

Sources

Official docs behind this checklist

Browse all launch guides · Read resources · How to make and check your next change

FAQ

FAQ for builders before launch

Does a variable in [build.environment] in netlify.toml reach my function?

No. Netlify says variables declared in a Netlify configuration file are not available to serverless functions. Variables declared there have the Builds and Post processing scope.

Can a function read Netlify's build-time variables?

Only three. Netlify offers many read-only variables during the build, but only URL, SITE_NAME and SITE_ID are available to functions at runtime.