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
| Variable | Available in server? | Available in browser? | Use for |
|---|---|---|---|
| DATABASE_URL | ✅ Yes | ❌ No | Database, API keys, secrets |
| NEXT_PUBLIC_API_URL | ✅ Yes | ✅ Yes | Public API endpoints, feature flags |
11 min
Add NEXT_PUBLIC_ Prefix for Client Components
Env var undefined in browser.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.comcomponents/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_URLNever 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.
21 min
Correct .env File Names
Wrong filename — not loaded by Next.js# 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.env31 min
Restart Dev Server After .env Changes
Most overlooked stepterminal
# 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 loaded43 min
Set Env Vars on Vercel and Other Platforms
Works locally but undefined in productionYour .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 productionOr 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 variable53 min
Runtime Env Vars in App Router
Values available at runtime not just build timeNEXT_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
- Add NEXT_PUBLIC_ prefix to any env var accessed in Client Components
- Restart dev server after every .env change
- Set all env vars in your deployment platform dashboard before deploying
- Create .env.example with all key names (no values) for teammates
- Never put secrets in NEXT_PUBLIC_ variables — they are public
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