Skip to content

My App Works on My Computer but Is Broken When Deployed. Why?

6 min read

Your app runs flawlessly on your laptop, you deploy it, and the live version is a blank white screen or a 500 error. Nine times out of ten the cause is a missing environment variable: a secret or setting that exists on your machine but was never added to the hosting platform. The code is fine. The configuration around it is not.

Why this happens

When you build locally, your API keys and database URLs live in a file, usually .env or .env.local, sitting in your project folder. Your app reads them and everything works. That file is deliberately not uploaded when you deploy, because it holds secrets and shouldn't go into your code repository. So the deployed app looks for the same values, finds nothing, and either crashes or renders an empty page.

The AI agent that built your app wired everything up against your local file because that is what worked in front of you. It did exactly what you asked. It did not set those same values up on Vercel, Netlify, or Render, because you never asked it to, and it had no way to. That step is manual, it happens on the hosting side, and nothing in the demo hints that it is missing.

How to check

  1. Read the actual error, not the blank screen. On Vercel or Netlify, open your project, go to the latest deployment, and look at the build logs and runtime/function logs. A line like undefined is not a valid value, Missing SUPABASE_URL, or ECONNREFUSED points straight at config.
  2. List what your code expects. Search your project for process.env. (or import.meta.env.). Every unique name after that is a variable your app needs in production.
  3. Compare against what's set. In your hosting dashboard, open Settings → Environment Variables. Any name your code reads that is not in that list is your bug.

The fix

  1. Add each missing variable in the hosting dashboard, matching the name exactly, including case. DATABASE_URL and database_url are different variables to the platform.
  2. Use production values, not local ones. Your local database URL often points at localhost, which does not exist on the server. Paste the real hosted database URL, the live API keys, and the production domain.
  3. Mind the public prefix. Variables that must reach the browser need a prefix your framework recognises (NEXT_PUBLIC_, VITE_, PUBLIC_). Without it the value stays server-side and the browser sees undefined.
  4. Redeploy. Most platforms only pick up new variables on the next build. Adding a variable and refreshing the page does nothing until you trigger a fresh deployment.
  5. Confirm from the live URL, not localhost. Open the deployed site, repeat the action that broke, and check the function logs are now clean.

The trap to avoid

Do not commit your .env file to the repository to "make it work everywhere." That ships your secrets into your code history, where anyone with repo access, now or later, can read them. Keep secrets in the hosting platform's environment settings, and keep .env in your .gitignore. If you have already committed it, treat those keys as exposed and rotate them.

Where this fits

A missing environment variable is the single most common reason a working demo dies on deploy, and it is invisible until a real user, or you, hits the live URL. It travels with two siblings worth understanding: what environment variables you actually need in prod and why you only get 500 errors in production. The free Readiness Report runs against your real deployment and flags the variables your code reads but your host never received, before your first users find the blank screen. If you would rather have the whole config gap closed and verified for you, that is the Finishing Pass.