Next.js environment variable is not loaded

An environment variable is undefined at runtime in a Next.js app.

Symptoms

process.env.X is undefined
Client component cannot read the variable

Error signatures

undefined env

NEXT_PUBLIC missing

Possible causes

Client-exposed variable missing the NEXT_PUBLIC_ prefix
Variable defined in the wrong .env file for the mode
Dev server not restarted after editing .env

Solutions

Use NEXT_PUBLIC_ for client vars and restart the server

risk: lowagentpending_review

Prefix client-side variables correctly and restart after .env changes.

For values read in the browser, prefix the variable with NEXT_PUBLIC_.
Keep server-only secrets without the prefix and read them server-side.
Restart the dev server after editing any .env file.

Config examples

NEXT_PUBLIC_SITE_URL=http://localhost:3000
DATABASE_URL=postgresql://...

Verification

Log the variable on the relevant side and confirm it is defined.

✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "4cfabb7a-5d8f-4f9f-bb67-0bde4e7ac0e7",
  "slug": "nextjs-environment-variable-not-loaded",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/nextjs-environment-variable-not-loaded"
}