Next.js environment variables undefined in production: build time vs runtime.

Find the row that matches where your code reads the variable. The middle column is the moment its value is decided; anything you change after that moment is invisible to it.

The browser has no process.env. To give client code a value, Next.js does a text replacement during next build: each literal process.env.NEXT_PUBLIC_X becomes the string it had on the build machine. The Next.js docs are blunt about it: after the build, the app “will no longer respond to changes to these environment variables.”

• Set during the build, or it doesn’t exist. A host that injects variables only when the app starts, or a Docker image built without them, produces a bundle full of undefined.
• One image, many environments doesn’t work for `NEXT_PUBLIC_`. Promote a staging build to production and the browser keeps the staging values.
• Docker: pass browser values as ARG in the build stage, because ENV set only in the final stage arrives after next build has run. Server secrets belong in the runtime environment, not in ARG, where they end up in the image history.

// What you wrote (a client component)
const api = process.env.NEXT_PUBLIC_API_URL;

// What `next build` ships to the browser
const api = "https://api.example.com";

// ...or, if the variable wasn't set when the build ran
const api = undefined;

// Never inlined: dynamic lookups stay undefined in the browser
const name = "NEXT_PUBLIC_API_URL";
process.env[name];
const env = process.env;
env.NEXT_PUBLIC_API_URL;

Variables without the prefix stay on the server and are read from process.env when the code runs. When one still comes back undefined, it is usually one of these:

• The page was prerendered. A page with no request-time API (cookies(), headers(), connection()) is rendered during next build. Any variable it reads is baked into its HTML, and a variable that only exists at runtime is undefined there. Call await connection() in the page to render it per request, as the self-hosting guide shows.
• It lives in `.env.local`. That file is git-ignored by default, so it never leaves your laptop. Set the value on the host instead.
• You read it in a client component. Without NEXT_PUBLIC_, client code gets undefined by design. Read it in a server component and pass it down as a prop.
• The `.env` file is in `src/`. Next.js loads .env* files only from the project root.

You set variables in the project’s Env Vars tab. Each has a scope that decides which phases receive it:

• **NEXT_PUBLIC_* must not be runtime only. That scope keeps a value out of the build, which is exactly when Next.js inlines it. The browser gets `undefined`. Use production or all**.
• A runtime-only secret read in a static page is `undefined` too, for the same reason. Make that page dynamic, or move the read into a Route Handler or Server Action.
• Edits apply on the next deploy, server variables included. Each deploy carries its own copy of your variables, so redeploy after changing one. The build log confirms what went in: [canner] wrote 12 env var(s) to .env.production (build phase).
• A committed `.env.production` is replaced. Canner writes your project’s variables to .env.production for the build and again for the running app. Keep shared defaults in .env, which Next.js reads last, or move them to the Env Vars tab.
• Previews are their own builds. A NEXT_PUBLIC_ variable scoped preview is inlined into preview builds only, so previews can point the browser at a staging API without touching production.

When a browser value must change without a rebuild, stop using NEXT_PUBLIC_ for it and serve it at runtime. Two patterns cover most apps.

Pass it from a server component. The value is read per request and handed to the client component as a prop:

// app/settings/page.tsx (server component)
import { connection } from "next/server";
import { SettingsForm } from "./settings-form"; // "use client"

export default async function Page() {
  await connection(); // this page renders at request time
  return <SettingsForm apiUrl={process.env.API_URL!} />;
}

The same idea as an endpoint. The connection() call keeps Next.js from rendering the response once at build time:

• To check what a build actually inlined, search the client chunks for the value: grep -rl "api.example.com" .next/static/chunks. No match means the variable was empty at build time.
• If the name NEXT_PUBLIC_API_URL still appears in a chunk, the code reads it dynamically and it was never inlined.

// app/api/public-config/route.ts
import { connection } from "next/server";

export async function GET() {
  await connection(); // read per request, not frozen at build
  // Only values that are safe for anyone to see.
  return Response.json({
    apiUrl: process.env.API_URL,
    mapsKey: process.env.MAPS_BROWSER_KEY,
  });
}