Works locally, breaks live: fixing environment variables on Vercel

Your app runs perfectly on your computer. You deploy it to Vercel, and suddenly login fails, the database won't connect, or the page is blank. If your environment variables are not working on Vercel, you are in very good company. This is one of the most common problems for anyone building with AI tools, and the fix is usually five minutes.

What environment variables are

Environment variables are settings that live outside your code: API keys, database addresses, passwords. Your code reads them by name, like SUPABASE_URL, and the actual value is stored somewhere safer.

On your computer, they usually live in a file called .env.local in your project folder.

Why it works locally but not live

That .env.local file is (and should be) ignored by git, so it never gets uploaded. Your live site on Vercel has no idea what's in it. Same code, missing settings, broken app.

Fix 1: add the variables in Vercel

1. Open your project on vercel.com.
2. Go to Settings, then Environment Variables.
3. Add each variable from your .env.local: same name, same value.
4. Choose which environments it applies to. Vercel has Production (your live site), Preview (test deployments from other branches) and Development (your computer, via Vercel's tools). For most beginner apps, tick Production and Preview.

Names must match exactly. SUPABASE_URL and SUPABASE_Url are different variables.

Fix 2: redeploy

This is the step everyone misses. Vercel's docs say it directly: changes to environment variables are not applied to previous deployments, only to new ones. Adding a variable does nothing to the site that's already live.

After adding or changing variables, trigger a new deployment: push a new commit, or use Redeploy on your latest deployment in the Vercel dashboard.

Fix 3: check the public prefix

Some frameworks only let the browser see variables with a special prefix:

• Next.js: NEXT_PUBLIC_
• Vite: VITE_

If your front end code reads SUPABASE_URL but the browser needs it, it may have to be named NEXT_PUBLIC_SUPABASE_URL (or the VITE_ version), both locally and on Vercel.

The big warning: anything with these prefixes is bundled into your site and visible to every visitor. Only public values belong there, like a Supabase project address or its public (anon or publishable) key. Never put a secret key, a payment secret, or an AI API key behind a public prefix. If you're unsure which Supabase keys are safe, read is your Supabase anon key safe to expose?

Fix 4: read the error

If it still fails, open your deployment in Vercel and check the build logs and the function logs. Look for words like "undefined", "missing" or the variable's name. Then hand the error to your AI with this prompt:

My app works locally but fails on Vercel. Here is the error from the
Vercel logs: <paste>. Do not change code yet. List every environment
variable my code reads, say whether each is needed in the browser or
only on the server, and which ones need a NEXT_PUBLIC_ or VITE_ prefix.
Flag any secret that is currently exposed to the browser.

A quick checklist

• Every variable in .env.local also exists in Vercel, with the exact same name.
• The right environments are ticked (Production at least).
• You redeployed after the change.
• Browser-side variables have the right prefix, and none of them are secrets.

For the full pre-launch list, see our vibe coding security checklist.

Get the prompts and templates

The Deploy stage of the Vibe Coder Prompt Pack has copy-paste prompts for exactly this. The Ship-Safe Starter Kit includes a .env.example template and a pre-deploy checklist, and our free starter pack has a rule that keeps secrets out of public variables.

Vibe Shipped is independent and not affiliated with Vercel. Written with AI assistance and reviewed by a human.