Fix Environment Variables Not Working on Netlify

$ process.env.VARIABLE_NAME is undefined

Also appears as:

  • Environment variable is undefined
  • Cannot read properties of undefined (reading 'VARIABLE_NAME')
  • Error: Missing required environment variable
  • API key not found in environment

Symptoms

  • Environment variables work locally but not on Netlify
  • API calls fail because keys are undefined
  • Build succeeds but the site shows missing data
  • Some environment variables work but others don't

What Causes This Error

Variable not set in Netlify dashboard

Common

The most common cause: the variable exists in your local .env file but was never added to Netlify's environment variable settings. Netlify doesn't read your .env files.

Missing framework prefix for client-side access

Common

Most frameworks require a special prefix to expose variables to the browser. Next.js uses NEXT_PUBLIC_, Astro uses PUBLIC_, SvelteKit uses PUBLIC_, and Vite uses VITE_. Without the prefix, the variable is only available server-side.

Variable set in wrong scope

Occasional

Netlify lets you scope variables to specific deploy contexts (production, deploy-preview, branch-deploy). If your variable is scoped to production only, it won't be available in deploy previews.

Variable value contains special characters

Occasional

Variables with quotes, newlines, or special characters may not be parsed correctly. This is especially common with multi-line keys (like Firebase service account JSON).

Build cache serving stale values

Rare

After changing an environment variable, the build cache might still hold the old value. This is rare but can cause confusion when debugging.

How to Fix It

Fix 1: Add the variable in Netlify dashboard

  1. Go to your site in Netlify
  2. Navigate to Site settings > Environment variables
  3. Click 'Add a variable'
  4. Enter the variable name and value
  5. Select the appropriate scope (all deploys, production, preview, etc.)
  6. Trigger a new deploy

Verify: Redeploy and check if the variable is now accessible in your build logs.

Fix 2: Add the correct framework prefix

  1. Identify which framework you're using
  2. Rename the variable with the appropriate prefix
  3. Update your code to reference the prefixed variable name
  4. Update both your local .env file and Netlify dashboard
Framework prefixes for client-side access
Next.js:    NEXT_PUBLIC_API_URL=...
Astro:      PUBLIC_API_URL=...
SvelteKit:  PUBLIC_API_URL=...
Vite/React: VITE_API_URL=...
Gatsby:     GATSBY_API_URL=...
Nuxt:       NUXT_PUBLIC_API_URL=...

Verify: Check the browser console — the variable should now be defined in client-side code.

Fix 3: Check and fix variable scope

  1. Go to Site settings > Environment variables in Netlify
  2. Check the scope of each variable
  3. Ensure variables needed in deploy previews aren't scoped to production only
  4. For sensitive keys, use different values per scope

Verify: Test the variable in both production and deploy preview environments.

Fix 4: Handle special characters in values

  1. For multi-line values (like JSON keys), base64 encode the value
  2. Decode it in your application code at runtime
  3. Alternatively, use Netlify's UI which handles multi-line values better than the CLI
Encode a JSON key
# Encode
cat service-account.json | base64

# In your code, decode:
const key = Buffer.from(process.env.SERVICE_ACCOUNT_BASE64, 'base64').toString()

Verify: Verify the decoded value matches the original in your build logs (be careful not to log secrets).

Fix 5: Clear cache and redeploy

  1. Go to Deploys in your Netlify dashboard
  2. Click 'Trigger deploy'
  3. Select 'Clear cache and deploy site'
  4. Wait for the build to complete

Verify: If the variable works after cache clearing, the issue was stale cached values.

How to Prevent This

1.

Keep a .env.example file in your repo listing all required variables (without values) so new team members know what to set.

2.

Validate environment variables at build time — fail fast with a clear error message if required variables are missing.

3.

Use Netlify's team-level environment variables for shared secrets across multiple sites.

4.

Use the Netli.fyi app to quickly check your site's environment variable configuration.

5.

Document which variables need the client-side prefix in your project's README.

Perttu Lähteenlahti

Perttu Lähteenlahti

Developer Advocate at RevenueCat and creator of Netli.fyi. Building on Netlify since 2019. Writes from hands-on experience deploying dozens of production sites.

Manage Netlify on the go

Download Netli.fyi and monitor your sites, check deploys, and manage your projects from anywhere.

Google Play