Netlify: env vars not loading in functions [2026 fix]

Env vars undefined in Netlify Functions? Missing netlify.toml config or wrong deployment build. Deploy with build command, add [functions] section.

Netlify: env vars not loading in functions [2026 fix]

TL;DR

---

Common Error Messages

Here are exact console outputs you'll see at 2am:

``` ReferenceError: process.env.API_KEY is not defined at /var/task/src/functions/api.js:12:15 ```

``` undefined is not a function (process.env.DATABASE_URL) at Handler (/functions/query.js:5:3) ```

``` {"statusCode":500,"body":"{\"errorMessage\":\"Cannot read properties of undefined (reading 'split')\",\"trace\":[\"ReferenceError: Cannot read properties of undefined (reading 'split')\"]}"} ```

``` ENVIRONMENT variable MY_SECRET returned undefined in function execution ```

``` Error: process.env.STRIPE_KEY is undefined at module load time at Object.<module> (/var/task/src/functions/checkout.js:1:1) ```

---

The Problem: Side-by-Side Code

❌ Broken Setup

netlify.toml (missing or incomplete): ```toml [build] command = "npm run build" publish = "dist" ```

.env file (won't be read by functions): ``` API_KEY=sk_test_abc123 DATABASE_URL=postgres://... ```

functions/api.js: ```javascript const API_KEY = process.env.API_KEY; // ❌ undefined at runtime

exports.handler = async (event) => { const response = await fetch(https://api.example.com?key=${API_KEY}); return { statusCode: 200, body: JSON.stringify(response) }; }; ```

✅ Fixed Setup

netlify.toml (with functions config): ```toml [build] command = "npm run build" publish = "dist"

[functions] directory = "netlify/functions" node_bundler = "esbuild" external_node_modules = ["axios", "pg"]

[[env.production.context.production]] API_KEY = "sk_test_abc123" DATABASE_URL = "postgres://..." ```

Netlify UI (Dashboard → Site Settings → Build & Deploy → Environment):

netlify/functions/api.js: ```javascript const API_KEY = process.env.API_KEY; // ✅ defined via netlify.toml or UI

exports.handler = async (event) => { if (!API_KEY) { return { statusCode: 500, body: JSON.stringify({ error: "API_KEY not configured" }) }; } const response = await fetch(https://api.example.com?key=${API_KEY}); return { statusCode: 200, body: JSON.stringify(response) }; }; ```

---

Why This Happens

1. Local .env files don't deploy – Netlify doesn't commit .env to git. You must add vars via: - Netlify Dashboard UI (preferred for production secrets) - netlify.toml file (for non-sensitive defaults) - Environment context blocks in netlify.toml

2. Functions need explicit config – Unlike Next.js API routes, Netlify Functions require [functions] section in netlify.toml to enable Node bundler and env var injection.

3. Build-time vs. Runtime – Vars must be injected *before* function execution, which requires proper netlify.toml declaration. Missing this causes undefined at module load time.

Note on version specificity: These instructions apply to Netlify Functions as of 2026. If you're using Netlify Blobs or experimental features, behavior may differ—check [official Netlify Functions environment variables docs](https://docs.netlify.com/functions/overview/?fn-language=js#environment-variables).

---

Still broken? Check these too

1. Build cache poisoning – Old function bundles cached with undefined vars. Fix: Netlify UI → Deploys → Trigger Deploy → Clear cache and deploy.

2. Function bundling misconfiguration – node_bundler = "esbuild" vs "zisi" matters. If using TypeScript with tree-shaking, esbuild may strip apparent "unused" env var reads. Add external_node_modules list to your netlify.toml.

3. Env var scoped to wrong context – Variables in [env.production] won't load in preview deployments. Use [[env.CONTEXT.context.CONTEXT]] syntax or add to base [build.environment] section instead.

Also see: [related guide on Netlify secrets management](/?guide=netlify-secrets) and [debugging serverless functions locally](/?guide=debug-serverless).

---

Verification Checklist

---

Found a different variation? Drop it in the comments.