Fix: a setting shows as "undefined" in the browser of your Next.js app (NEXT_PUBLIC_ environment variable, tested repro, Next 16 + React 19.3)

A developer reproduced a Next.js bug where a client-side setting renders as "undefined" in the browser despite a passing build, tracing it to two causes: environment variables missing the NEXT_PUBLIC_ prefix, and variables added after `next build` ran. The fix is to rename the variable and its reader with the NEXT_PUBLIC_ prefix, then rebuild; the repro was verified on a synthetic app with Next 16.4.3, React 19.3.1 and headless Chrome, and the developer notes secret keys must never receive the public prefix.

A setting such as a booking link works on the server but shows up as undefined in the browser, with no error message and a passing build. In an AI-built or hand-built Next.js app, the usual causes are a variable name without the NEXT PUBLIC prefix, or a variable added after the app was built. We reproduced it on a small synthetic app, applied the smallest fix, and checked it by clicking the button in headless Chrome. Below: the symptom, the cause, the fix, how we verified it, and what we did not test. 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. app/ folder , with a setting stored as an environment variable a .env.local file or your host's "Environment Variables" page . undefined for example a link that goes to undefined/book . 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". There is no red error. This is what we saw in headless Chrome after clicking the button: 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 . | Item | Version | |---|---| | Node.js | 20.19.2 | | next | 16.4.3 Turbopack | | react / react-dom | 19.3.1 | | Browser | Google Chrome 155.0.8059.84, headless, via playwright-core 1.64.1 | | OS | Linux, single machine | 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 https://nextjs.org/docs/app/guides/environment-variables . That gives two common ways to get undefined : 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" . 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 next start still gave Public reports of the same family: the Next.js discussion 74624 https://github.com/vercel/next.js/discussions/74624 Next 15 + React 19 + Turbopack and a Stack Overflow answer https://stackoverflow.com/questions/68205264/environment-variables-in-nextjs-are-undefined 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. process.env.NEXT PUBLIC BOOKING URL . npx next build , start again; in dev, stop and restart npm run dev . On a host, trigger a new deploy after saving the variable. app/BookButton.js 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 js - <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. 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. Run on 2026-10-24 on a small synthetic app three copies: before, after, and "added too late" , using headless Chrome with default settings. next dev : https://booking.example.test/book . 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. VITE names and import.meta.env . A process.env name and aliasing cases, and the "read it on the server and pass it down" alternative. package.json and the name has no typos or spaces around = . https://booking.example.test . The original guide, with the before/after files, is on The Agent Ledger: A setting shows as "undefined" in the browser: Next.js fix https://theagentledger.ai/fixes/next-public-env-undefined-in-browser/?utm source=devto&utm medium=post&utm campaign=fix04 . AI disclosure: This article was written with the help of AI. The reproduction and the before/after browser runs described above were actually performed and checked against the logs before publishing.