Fix Next.js Environment Variables Missing in Production

When Next.js environment variables work locally but disappear in production, first identify where the value is read. Browser variables using NEXT_PUBLIC_ are embedded during the build. Server-only values belong in the server environment. A static export has no Next.js server available to read new runtime settings.

What does the failure look like in a real release?

Consider a website whose contact form should call a separate API. Locally the API URL comes from an ignored environment file. The release job has no equivalent value, so the generated browser bundle contains an empty or incorrect destination. Uploading that bundle successfully does not make the configuration correct.

Start with the failed browser request, not the hosting dashboard. Record the destination hostname, status code, build identifier, and release time. If the browser calls localhost or a staging service, you have a configuration or artifact problem before you have evidence of a backend outage.

Step 1: classify public configuration and private credentials

An API base URL intended for direct browser requests is public configuration. A database password, private signing key, or provider secret is not. Prefixing a secret with NEXT_PUBLIC_ exposes it to visitors because it becomes part of delivered JavaScript. Keep privileged calls behind an authenticated backend instead.

Write a small configuration inventory before changing names: variable, consumer, environment, and whether it is required during build or runtime. For example, the browser may need an API origin while a Laravel API separately needs mail credentials. Those values belong to different deployment systems and should not be copied together.

Step 2: validate required values before building

The following Node script checks a public API origin without printing its value. Run it in the same job and shell environment as the production build. It illustrates a fail-fast check; adapt permitted origins and protocols to your deployment rather than accepting arbitrary destinations.

// scripts/check-public-config.mjs
const raw = process.env.NEXT_PUBLIC_API_BASE_URL;
if (!raw) throw new Error("NEXT_PUBLIC_API_BASE_URL is required");
const api = new URL(raw);
if (api.protocol !== "https:") {
  throw new Error("Production API origin must use HTTPS");
}
if (["localhost", "127.0.0.1"].includes(api.hostname)) {
  throw new Error("Production API must not target localhost");
}
console.log("Public API configuration validated");

Use a direct reference such as process.env.NEXT_PUBLIC_API_BASE_URL in browser code. Dynamic lookups through a variable name are a different pattern and are not substituted in the same way. A fallback can be useful for development, but a silent production fallback can hide a missing release setting.

Step 3: rebuild with the intended deployment settings

1. Confirm which CI job or local machine creates the production artifact. Configure required public values there before the build starts.
2. Use the project's documented production build command and retain its complete log and release identifier.
3. Preview the generated production artifact. Inspect the form request destination without submitting a real lead.
4. Deploy that exact artifact. Changing a dashboard value after a static bundle was built does not rewrite that bundle.
5. Verify a fresh browser session after publication and revalidate cached HTML and assets through the normal release procedure.

Keep environment files out of public assets, release archives, and source control. Inspect filenames as well as values: uploading the whole project directory to shared hosting can expose files that were never intended to be web content. Publish the export directory or the supported server artifact for your hosting model.

Step 4: separate static hosting from a Node deployment

With an exported website on Apache or LiteSpeed, settings needed by browser code must be available when generating the export. The upload target serves files; it does not run a Next.js request handler to reinterpret an environment variable. If you need runtime configuration, design an explicit configuration endpoint containing only public values.

A Node-hosted application can read server-only runtime variables in request-time code, but that does not change how already-built public variables work. Document the rendering and hosting mode before applying advice from another project. The same environment name can have different consequences when consumed by a static page and a server handler.

How do you prove the fix and prevent another incident?

Verify the real user action in staging with external writes mocked or sandboxed. A successful page load alone is weak evidence: the failure may occur only when submitting a form or loading an authenticated dashboard. Test both the expected configuration and a build with the required setting intentionally absent.

Add the variable inventory to deployment documentation, assign ownership for each environment, and keep an artifact checksum with the release. Never paste a full environment dump into a bug report. The useful evidence is whether a key is present, its intended purpose, and the destination of a public request.

Can one built artifact serve several environments?

Yes, but only when the configuration model supports it deliberately. If public settings are embedded in a browser bundle, that bundle carries the values used to build it. Promoting the same files from staging to production also promotes those embedded values. Use separate builds or an explicit public runtime configuration mechanism.

For example, keep a staging contact form connected to a sandbox API and inspect that origin before promotion. If an artifact contains the staging origin, changing a production environment setting beside the uploaded files will not correct it. The release checklist should identify who builds the artifact, where configuration enters, and how the browser destination is verified.

For route failures after export, use the Next.js static-hosting 404 checklist. Our backend and cloud engineering service covers deployment configuration reviews. Send the build log and hosting model when requesting help, with secrets removed.

Official references and further reading

Next.js: environment variables

Next.js: static exports