Next.jsEnvironmentError Fix2026 Updated

Next.js NEXT_PUBLIC_ Env Variable Undefined— Fixed [2026]

Also covers: process.env undefined in Next.js · env var not working in production

January 20265 min readNext.js 13–15 · Vercel

⚡ Next.js Env Variable Rules

.env.local
# Server-only (NOT visible in browser)
DATABASE_URL=mongodb+srv://...
JWT_SECRET=supersecretkey

# Client-safe (visible in browser bundle — use for public values only)
NEXT_PUBLIC_API_URL=https://api.myapp.com
NEXT_PUBLIC_STRIPE_KEY=pk_live_...

Server vs Client Env Vars in Next.js

VariableAvailable in server?Available in browser?Use for
DATABASE_URL✅ Yes❌ NoDatabase, API keys, secrets
NEXT_PUBLIC_API_URL✅ Yes✅ YesPublic API endpoints, feature flags
1

Add NEXT_PUBLIC_ Prefix for Client Components

Env var undefined in browser
1 min
.env.local
# ❌ WRONG — no prefix, only available on server
API_URL=https://api.myapp.com

# ✅ CORRECT — NEXT_PUBLIC_ prefix makes it available in browser
NEXT_PUBLIC_API_URL=https://api.myapp.com
components/FetchButton.jsx
'use client'

// ❌ undefined in browser — no NEXT_PUBLIC_ prefix
const url = process.env.API_URL

// ✅ works in browser
const url = process.env.NEXT_PUBLIC_API_URL

Never put secrets (JWT secrets, database passwords, private API keys) in NEXT_PUBLIC_ variables. They are embedded in your JavaScript bundle and visible to anyone who views your source.

2

Correct .env File Names

Wrong filename — not loaded by Next.js
1 min
# Next.js loads these files in order (later = higher priority):
.env                # base values — committed to git (no secrets)
.env.local          # local overrides — in .gitignore
.env.development    # development-only
.env.production     # production-only
.env.local          # always loaded, highest priority

# ❌ Wrong names that Next.js does NOT auto-load:
.env.dev
.env.prod
config.env
3

Restart Dev Server After .env Changes

Most overlooked step
1 min
terminal
# Next.js reads .env files only on startup
# After any .env change:
Ctrl+C          # stop the server
npm run dev     # restart — env vars are now loaded
4

Set Env Vars on Vercel and Other Platforms

Works locally but undefined in production
3 min

Your .env.local file is in .gitignore and never deployed. Set production variables through your platform.

Vercel CLI
vercel env add NEXT_PUBLIC_API_URL production
vercel env add DATABASE_URL production
Or in Vercel Dashboard
# Vercel → your project → Settings → Environment Variables
# Add each variable and select which environments it applies to
# (Production / Preview / Development)
Other platforms
# Netlify: Site settings → Environment variables
# Railway: Project → Variables tab
# Render: Environment → Add environment variable
5

Runtime Env Vars in App Router

Values available at runtime not just build time
3 min

NEXT_PUBLIC_ variables are inlined at build time. If you change them, you must rebuild. For values that change without rebuilding, use runtime configuration.

app/api/config/route.js
// Expose runtime config via an API route
export async function GET() {
  return Response.json({
    apiUrl: process.env.API_URL,  // server-only var
    featureFlags: process.env.FEATURE_FLAGS,
  })
}

// In client component — fetch at runtime
const { apiUrl } = await fetch('/api/config').then(r => r.json())

Prevention

Frequently Asked Questions

Why is NEXT_PUBLIC_ env variable undefined in Next.js?+
If defined correctly in .env.local, a NEXT_PUBLIC_ variable is undefined in the browser when: 1) the dev server was not restarted after adding it, 2) it is missing NEXT_PUBLIC_ prefix (server-only without it), or 3) it is not set in your deployment platform (Vercel/Netlify dashboard).
What is the difference between NEXT_PUBLIC_ and regular env vars in Next.js?+
Variables with NEXT_PUBLIC_ prefix are inlined into the browser JavaScript bundle at build time — any user can see them. Variables without the prefix are only available in server-side code (API routes, Server Components, getServerSideProps). Never put secrets in NEXT_PUBLIC_ variables.
Next.js env variable works locally but undefined in production?+
You need to add the variable to your deployment platform (Vercel, Netlify, Railway etc.). .env.local is in .gitignore and is never deployed. Set environment variables through your platform's dashboard or CLI.
Can I use process.env in a Client Component?+
Only NEXT_PUBLIC_ variables work in Client Components. Regular process.env variables (without the prefix) are server-only and will be undefined in the browser. If you need to pass a server value to a client, pass it as a prop from a Server Component.
How do I add env vars to Vercel?+
Go to your project in the Vercel dashboard → Settings → Environment Variables. Add each variable for Production, Preview, and Development. Or use the CLI: vercel env add MY_VAR. Changes take effect on the next deployment.
NEXT_PUBLIC_ variable is undefined after adding to .env.local — why?+
You must restart the Next.js dev server after changing .env files. The server reads them at startup. Ctrl+C the server and run npm run dev again.

Need Expert Help?

We Build Production-Grade Next.js Apps

Softplix builds full-stack Next.js applications. Need help with environment configuration or Vercel deployment? We can help.

Talk to an Engineer