It works in the preview but breaks when I deploy it
Any AI coding tool Last checked 2026-10-14
In nine cases out of ten the deployed environment is missing something the preview had: an environment variable, a build step, a database connection, or a hardcoded localhost URL. Open the deploy logs and the browser console first — the preview told you nothing because it never ran the production build.
What you saw
The app runs perfectly in the tool's preview pane or on localhost. Deployed, you get a blank white screen, a 500, or a page that loads but where nothing saves.
The browser console usually has the real answer: a 404 on an asset, a CORS error, process.env.X is undefined, or a failed request to http://localhost:3000.
What it actually means
The preview is a development server. It is lenient: it injects dev variables, serves unbundled files, ignores some type and build errors, and often runs alongside a dev database. Production does none of that.
The usual culprits, in the order you should check them:
- Environment variables not set in the host. Your local
.env is not uploaded. Production has nothing. - Client vs server variables. Only prefixed variables reach the browser (
NEXT_PUBLIC_, VITE_). A secret without the prefix is undefined in client code — which is correct, but crashes if you read it there. - Hardcoded localhost. An API base URL written for dev that does not exist in production.
- A build error the preview tolerated. Type errors or missing dependencies that only fail on a real build.
- Database and auth config. Production points at a different database, or the redirect URL allow-list does not include the deployed domain.
The fix
Read the deploy log before changing anything. A failed build says exactly which file and line. Guessing at this stage wastes an hour.
Open the deployed site and check the browser console and network tab. White screen plus a console error is a solved problem; white screen plus no information is not.
Reproduce it locally with a real production build. This catches most of these in a minute.
npm run build && npm run start
# or, for vite:
npm run build && npm run preview
Copy every variable from .env into the host's environment settings, then redeploy. Most hosts do not pick up new variables without a rebuild.
Search the codebase for hardcoded URLs and replace them with an environment variable that differs per environment.
grep -rn "localhost\|127.0.0.1" src/
Add the deployed domain to the allow-lists it needs: auth redirect URLs, CORS origins, and any API key domain restrictions.
How to stop it happening again
Keep a committed .env.example listing every variable the app needs, with no secret values. It is the checklist for every new environment.
Make the app fail loudly at startup if a required variable is missing, instead of rendering a blank page. A clear crash beats a white screen.
Run the production build locally before every deploy, or in CI on every push.
Never hardcode a URL. One base-URL variable, set per environment.
Deploy early and often. The first deploy of a three-week-old project is a long debugging session; the tenth deploy of a one-day-old project is thirty seconds.
Related questions
Why is my environment variable undefined in the browser?
Client-side code only receives variables with the framework's public prefix, such as NEXT_PUBLIC_ or VITE_. Unprefixed variables stay server-side by design. If you need a secret in the browser, you do not — move that call to the server.
Blank white screen with nothing in the console. Where do I start?
Check the deploy log for a failed build, then check whether the page is serving a 404 for its JavaScript bundle. A wrong base path or output directory is the usual cause.
It worked yesterday and I changed nothing.
Something else changed: an expired key or token, a dependency resolved to a new version because there is no lockfile, or a provider's free tier paused the database. Check the deploy log timestamp against the last successful one.