Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A Next.js environment variable is undefined in the browser or after deploy

Errorprocess.env.API_URL is undefined

Short answer

Next.js only gives the browser variables whose names start with NEXT_PUBLIC_, and it copies their values into the JavaScript at build time. A variable without the prefix, read through a dynamic lookup, set after the build, or stored in a .env file that Next.js never loads will be undefined. Find which of the four applies, then rebuild.

  • Applies to Next.js 15, Next.js 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Say where the code runs. A Server Component, route handler or proxy reads the real environment. Code that ships to the browser only sees values that were copied in during next build. Search the build output for the value to see whether the copy happened.

    grep -rn "process.env" app src components lib 2>/dev/null | head -30
    # after a build: is the value inside the browser bundle?
    npx next build && grep -rl "the-value-you-expect" .next/static | head
  2. 2Match what you see, then jump to its fix

    1. 1The value is set on the server and printed in the terminal, yet it is undefined inside a Client Component or an event handler.The name has no NEXT_PUBLIC_ prefix but the code runs in the browserFix
    2. 2process.env.NEXT_PUBLIC_X works when typed out, but the same name is undefined when built from a string or taken from a copy of process.env.The variable is read through a dynamic lookupFix
    3. 3Works with next dev. After next build or in a Docker image, the NEXT_PUBLIC_ value is old, empty or the same in every environment.The value was set after the build, or the build ran with other valuesFix
    4. 4The variable is missing everywhere, including the server, or a value in .env.local is ignored in tests.Next.js does not load the .env file you editedFix

What does the error look like?

  • process.env.API_URL is undefined
  • TypeError: Cannot read properties of undefined
  • The variable prints in the terminal but is empty in the browser
  • The value works with next dev but is wrong after next build

Cause 1 of 4

The name has no NEXT_PUBLIC_ prefix but the code runs in the browser

1Check

Variables without the prefix stay in the Node.js environment. Find the file that reads the variable and check whether it has 'use client' or is imported by one.

grep -rln "use client" app src components 2>/dev/null
grep -rn "process.env.API_URL" app src components lib 2>/dev/null

2Fix

For a value that is safe to show to anyone, rename it with the NEXT_PUBLIC_ prefix and update every reader. For a secret, keep the name as it is and read it on the server only, then pass the result to the browser.

# .env
NEXT_PUBLIC_API_URL=https://api.example.com

// Client Component
const base = process.env.NEXT_PUBLIC_API_URL

3Verify

Restart the dev server (or rebuild) and print the value in the browser console.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 4

The variable is read through a dynamic lookup

1Check

Next.js replaces the exact expression process.env.NEXT_PUBLIC_NAME. A lookup with a variable key, or a copy such as const env = process.env, is not replaced.

grep -rnE "process\.env\[|= process\.env\b|\{[^}]*\} = process\.env" app src components lib 2>/dev/null

2Fix

Write the full name on every read.

// does not work in the browser
const key = 'NEXT_PUBLIC_ANALYTICS_ID'
const id = process.env[key]

// works
const id = process.env.NEXT_PUBLIC_ANALYTICS_ID

3Verify

Rebuild and search the browser bundle for the value.

npx next build && grep -rl "the-value-you-expect" .next/static | head

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 4

The value was set after the build, or the build ran with other values

1Check

NEXT_PUBLIC_ values are frozen into the JavaScript when next build runs. Changing the variable on the running server, or building one image and promoting it between environments, does not change them.

env | grep NEXT_PUBLIC_
docker build --help | grep -i build-arg

2Fix

Set the variable in the environment of the build step and rebuild. If one build must serve several environments, read the value on the server at request time instead, after a request-time API such as connection() has opted the page into dynamic rendering, or hand it to the client through your own API.

// app/page.tsx (Server Component, read at request time)
import { connection } from 'next/server'

export default async function Page() {
  await connection()
  const apiUrl = process.env.API_URL
  return <p>{apiUrl}</p>
}

3Verify

Change the variable, restart the server and reload the page. The new value shows without a rebuild.

API_URL=https://staging.example.com npm run start

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 4

Next.js does not load the .env file you edited

1Check

Next.js loads .env files from the project root, not from src. It looks in process.env first, then .env.$(NODE_ENV).local, .env.local, .env.$(NODE_ENV) and .env. When NODE_ENV is test, .env.local is skipped.

ls -a . src | grep -E "^\.env"
echo "NODE_ENV=$NODE_ENV"

2Fix

Move the file to the project root, put test values in .env.test, and restart. If a tool outside Next.js needs the same files, load them with @next/env.

mv src/.env.local ./.env.local

// jest or script setup
import { loadEnvConfig } from '@next/env'
loadEnvConfig(process.cwd())

3Verify

Restart next dev and print the variable from a Server Component or route handler. It now has a value.

npm run dev

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Name every browser-visible variable with NEXT_PUBLIC_ and keep secrets without it.
  • Always write process.env.NEXT_PUBLIC_NAME in full, never through a variable or a copy.
  • Pass NEXT_PUBLIC_ values as build arguments in CI and in Docker builds, and rebuild when they change.
  • Keep .env files in the project root and out of git, except shared defaults.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.