Fix: process.env Variables Are Undefined in Your App
Quick Answer
For client-side variables, prefix with NEXT_PUBLIC_. For server-side, use them only in API routes or server components. Create .env.local (not .env) for local development. Restart your dev server after adding new variables.
Symptoms
- !process.env.DATABASE_URL is undefined
- !NEXT_PUBLIC_ variables work but server-side ones don't
- !Environment variables work locally but not in production
- !Error: supabaseUrl is required
Step-by-Step Fix
Check the NEXT_PUBLIC_ prefix
Variables accessed in client components MUST start with NEXT_PUBLIC_. Server-only variables (API keys, secrets) should NOT have this prefix — they go in API routes and server components only.
Use .env.local not .env
Next.js loads .env.local for local development. Create this file in your project root. Add your variables one per line: NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
Restart the dev server
Next.js only reads .env files at startup. After adding or changing variables, stop the dev server (Ctrl+C) and restart with npm run dev.
Add to production separately
In Vercel: Project Settings > Environment Variables. In Cloudflare: wrangler secret put VARIABLE_NAME. In Railway: Service > Variables tab. Production env vars are NOT read from .env.local.
Frequently Asked Questions
Production environments don't read .env.local. You must add each variable to your hosting platform (Vercel, Railway, Cloudflare) separately.
Only for variables that are safe to expose to the browser (Supabase URL, Stripe publishable key). Never prefix secret keys, API tokens, or database passwords.
Related
Weekly Newsletter
Get next week's fix before you need it.
Join developers getting weekly vibe coding tips, error fixes, and tool updates.
Subscribe on Substack →