Fix: a setting shows as "undefined" in the browser of your AI-built Next.js app (environment variable)

By The Agent Ledger. Drafted with AI assistance and reviewed by the publisher. Tested 2026-10-24.

Short answer: If a setting such as your booking link or API address works on the server but shows up as undefined in the browser, either the variable's name doesn't start with NEXT_PUBLIC_, or you added it after the app was built. The smallest fix is to rename it (and the line of code that reads it) with the NEXT_PUBLIC_ prefix, then rebuild. Verified on a synthetic app only.

Prerequisites

• A Next.js app using the App Router (an app/ folder), with a setting stored as an environment variable (a .env.local file or your host's "Environment Variables" page).
• Terminal access, or your AI tool's code view and your host's settings page.
• The symptom: a button, link or request in the browser uses the text undefined (for example a link that goes to undefined/book). There is no error message, and the build passes.
• No keys or accounts are needed for this fix.
• Only rename settings that are safe for anyone to see. A NEXT_PUBLIC_ value is copied into the code every visitor downloads. Secret keys (service-role keys, payment secrets, passwords) must never get this prefix. See "Security notes".

The exact symptom

There is no red error. This is what we saw in headless Chrome after clicking the button (script: pw/check.js):

text shown after clicking "Book a call": "undefined/book"

The page's code was process.env.BOOKING_URL + "/book", and BOOKING_URL=https://booking.example.test was set in .env.local. The build log even says Environments: .env.local and exits 0. If your code sends that value to a service, you will typically see failed requests or undefined inside a URL in your browser's Network tab instead (we did not test that part).

Versions we used

Cause

Next.js runs your code in two places: on the server, and in your visitor's browser. The browser can't see your server's settings. To let it see a setting, Next.js copies the value into the downloaded JavaScript when you run next build, but only for variables whose names start with NEXT_PUBLIC_, and only if the variable exists at that moment (official docs).

That gives two common ways to get undefined:

1. No prefix. BOOKING_URL stays on the server. In the browser, process.env.BOOKING_URL is empty. In our built bundle the code was still a lookup at click time: process.env.BOOKING_URL+"/book" (bundle-grep.log).
2. Added too late. NEXT_PUBLIC_BOOKING_URL is right, but it wasn't set when next build ran (for example you added it to your host's settings after the last deploy). The value is "frozen" at build time, so the browser still gets undefined until you rebuild. We reproduced this too: building with no variable, then adding .env.local and restarting next start still gave undefined.

Public reports of the same family: the Next.js discussion #74624 (Next 15 + React 19 + Turbopack) and a Stack Overflow answer saying env files are read when the server starts and production needs a rebuild. We found these through web search and did not measure how common the problem is, or how often AI tools cause it.

Smallest working fix

1. Rename the variable everywhere it is set (.env.local and your host's settings) from BOOKING_URL to NEXT_PUBLIC_BOOKING_URL.
2. Change the code that reads it to the same name, written exactly as process.env.NEXT_PUBLIC_BOOKING_URL.
3. Rebuild and redeploy (locally: stop the server, run npx next build, start again; in dev, stop and restart npm run dev). On a host, trigger a new deploy after saving the variable.

Before (shows undefined/book): app/BookButton.js

"use client";
import { useState } from "react";

export default function BookButton() {
  const [link, setLink] = useState("");
  return (
    <div>
      <button onClick={() => setLink(process.env.BOOKING_URL + "/book")}>Book a call</button>
      <p id="link">{link}</p>
    </div>
  );
}

.env.local: BOOKING_URL=https://booking.example.test

After (shows the real link)

-      <button onClick={() => setLink(process.env.BOOKING_URL + "/book")}>Book a call</button>
+      <button onClick={() => setLink(process.env.NEXT_PUBLIC_BOOKING_URL + "/book")}>Book a call</button>

.env.local: NEXT_PUBLIC_BOOKING_URL=https://booking.example.test

Write it exactly as process.env.NEXT_PUBLIC_NAME. Per the Next.js docs and the discussion linked above, forms like process.env[name], saving process.env in a variable first, or optional chaining (process?.env?.NAME) are not replaced. We did not test those forms.

If the value must be changeable without rebuilding, or must stay secret, don't use NEXT_PUBLIC_. Read the value in server code and give the browser only what it needs, for example through your own API route. We did not test that approach.

Copyable prompt for your AI coding tool

In my Next.js App Router app, a setting works on the server but is undefined in the browser. Find every place in files marked "use client" (or components imported by them) that reads process.env.SOMETHING where SOMETHING does not start with NEXT_PUBLIC_. For each one, tell me whether the value is safe for any visitor to see. For the safe ones only, rename the variable to NEXT_PUBLIC_SOMETHING in the code, in .env.local and in .env.example, and write the access exactly as process.env.NEXT_PUBLIC_SOMETHING (no optional chaining, no process.env[name], no aliasing). For secrets (keys, tokens, passwords), do NOT add the prefix; instead move that code to a server route and tell me. Do not change anything else, show me the diff, and remind me to set the renamed variables on my host and redeploy.

Review the diff yourself and check no secret got the prefix. We did not test this prompt in any AI tool.

How we verified

Run on 2026-10-24 in fix-04/before, fix-04/after and fix-04/late, using headless Chrome with default settings (script: pw/check.js, which opens the page, clicks "Book a call" and prints the text shown).

1. Builds pass either way: next build exited 0 for before and after (before-build.log, after-build.log). The build does not catch this.
2. Before, production (next build + next start): after the click the page showed undefined/book (before-prod-browser.log).
3. Before, dev (next dev): same result, undefined/book (before-dev-browser.log).
4. After, production and dev: the page showed https://booking.example.test/book (after-prod-browser.log, after-dev-browser.log).
5. Bundle check: the built "before" code still reads process.env.BOOKING_URL at click time, while the "after" code has the link written into it (bundle-grep.log).
6. Added-too-late case (fix-04/late, correctly named variable):
7. built with no .env.local, then started: undefined/book (late-1-prod-browser.log);
8. then added .env.local and restarted the server without rebuilding: still undefined/book (late-2-prod-browser.log);
9. then rebuilt and restarted: https://booking.example.test/book (late-3-prod-browser.log).

Every run also logged one unrelated 404 resource error that we did not identify (probably a missing icon file); we did not confirm which file it was.

Files: see the downloads below.

Not verified

• Other browsers (Firefox, Safari) and real phones or visitors.
• Other Next.js, React or Node versions, and the Pages Router.
• Vercel, Netlify, Cloudflare, Lovable, Bolt or other hosts: where and when they apply variables during their build. We only simulated "variable missing at build time" locally.
• Vite-style apps (VITE_ names and import.meta.env). A third-party migration guide says exported Lovable apps need VITE_ renamed to NEXT_PUBLIC_; we did not test that.
• The optional-chaining, process.env[name] and aliasing cases, and the "read it on the server and pass it down" alternative.
• What a real service request does when given an undefined URL; we only checked the text the page built.
• Code generated by Cursor, Lovable, Bolt or v0; our app is hand-written and synthetic. We did not measure how often AI tools produce an unprefixed name.
• Whether the AI prompt produces a correct and safe diff in any tool.

Troubleshooting

• Still undefined after renaming: you probably didn't rebuild. Stop the server, rebuild, start again; on a host, redeploy after saving the variable.
• Works in npm run dev but not on your live site: the host's build may not have the variable. Add it in the host's settings under the exact same name, then redeploy.
• Check that .env.local is in the project root (the folder with package.json) and the name has no typos or spaces around =.
• Mixed up the two places: a variable set only on your laptop isn't on your host, and vice versa.

Security notes

• Anything named NEXT_PUBLIC_ ends up in the code anyone can download and read. Use it only for values meant to be public (a booking link, a public analytics ID, a publishable key). Never for a service-role key, secret key, password or token.
• Never paste real keys into an AI chat; use placeholders like https://booking.example.test.
• Don't commit .env.local to a public repository.

Downloads

Synthetic example files from our test. No real keys or data.

• bookbutton.diff: Before/after diff of the button component
• before-BookButton.js: Before: component that shows undefined in the browser
• after-BookButton.js: After: component reading the NEXT_PUBLIC_ variable
• before-build.log.txt: Build log before the fix (passes; the build does not catch this)
• after-build.log.txt: Build log after the fix
• before-prod-browser.log.txt: Headless Chrome check before the fix, production (undefined/book)
• before-dev-browser.log.txt: Headless Chrome check before the fix, dev mode (undefined/book)
• after-prod-browser.log.txt: Headless Chrome check after the fix, production (real link)
• after-dev-browser.log.txt: Headless Chrome check after the fix, dev mode (real link)
• bundle-grep.log.txt: What the built browser code contains before and after
• late-1-prod-browser.log.txt: Added-too-late case, step 1: built with no variable (undefined/book)
• late-2-prod-browser.log.txt: Added-too-late case, step 2: variable added, no rebuild (still undefined/book)
• late-3-prod-browser.log.txt: Added-too-late case, step 3: rebuilt (real link)
• check.js: Playwright script used for the browser check
• run.sh: Shell script that started each server and ran the check