My App Shows a Blank White Screen in Production

The deploy goes green. You open the production URL and get nothing. White page, no error text, no spinner. View source shows your HTML shell and a script tag, so something did ship. The app simply refuses to draw itself.

The blank white screen is the least informative failure in web development, which is why it feels so much worse than a stack trace. It is not really a bug category. It is what a single-page app looks like when anything at all throws before the first render finishes — and React, by design, unmounts the whole tree rather than showing you half an app.

The real error is almost always one keystroke away in the browser console. The catch is that in a production build it will be minified into something like "Cannot read properties of undefined (reading 'map')" pointing at column 40218 of a file named index-8f2a91.js. Here is how to read it anyway, and what each of the usual causes looks like when you do.

Read three places before you touch any code

Do this in order. Every minute spent guessing is a minute you could have spent knowing.

The browser console. Open DevTools on the production URL and hard-reload. You are looking for the first red line, not the last one. Everything after the first exception is downstream noise.

The Network tab. Filter to JS and CSS. If your main bundle returns 404 or, worse, returns 200 with HTML content, your app never loaded at all and the console will be quiet — a completely different failure than a runtime crash.

The deploy logs. Some hosts publish a build that half-succeeded. If the build output directory was empty or the wrong folder was served, the logs say so plainly while the browser says nothing.

Those three signals split the problem cleanly: console error means your code ran and threw; 404 on the bundle means your code never ran; a silent console with a 200 on everything means your app rendered nothing on purpose.

Cause 1: a runtime error on the first render

This is the most common one, and AI-generated frontends produce a very specific flavor of it: code that assumes data has already arrived. A component maps over 'items' before the fetch resolves, or reads 'user.profile.name' when user is still null. Locally you never saw it because your dev database always had a seeded row and the request came back in 4ms.

The fix is not a try/catch around the render. It is guarding the shape: default to an empty array, render a loading state while data is undefined, and stop treating "loaded" and "non-empty" as the same condition. If a whole class of these is scattered across the app, that is a pattern-level problem worth handling all at once — our guide on fixing AI-generated code covers how to sweep them systematically rather than one crash at a time.

While you are there, add an error boundary at the root. It converts every future white screen into a visible message, which is the difference between a five-minute fix and an evening.

Cause 2: environment variables that are undefined in the browser

The second-most common cause, and the one most specific to deployed builds. Your app reads a Supabase URL or an API base URL from an environment variable, that variable was never set on the host, and the client library throws during initialization — before a single component mounts.

Two details trip people up repeatedly. First, only prefixed variables reach the browser: NEXT_PUBLIC_ in Next.js, VITE_ in Vite, REACT_APP_ in Create React App. Miss the prefix and the value is undefined in the bundle no matter how correctly you set it in the dashboard. Second, these are inlined at build time, so setting the variable and clicking "restart" does nothing — you must trigger a fresh build. If this is your situation, the full set of traps is in why my environment variables are not working.

Cause 3: the bundle 404s because of a base path

Your index.html asks for /assets/index-8f2a91.js and the server returns your index.html instead, with a 200 status. The browser tries to parse HTML as JavaScript, gives up, and you get a white page with a console message about an unexpected token '<'.

This happens when the app is served from a subdirectory, when the Vite 'base' or Next.js 'basePath' setting does not match where the app actually lives, or when a catch-all rewrite rule intercepts asset requests. Check the Network tab for the response body of the JS request — if it starts with a doctype, this is your bug.

Cause 4: the wrong directory got deployed

Static hosts need to know which folder holds the built output: dist for Vite, build for Create React App, out for a Next.js static export. Point the host at the repo root and it will happily serve a shell with no assets, or the source index.html that references a nonexistent /src/main.tsx. Nothing errors. You just get white.

Cause 5: an auth guard that never resolves

A route wrapper checks for a session, the session check fails silently because cookies are not being set on the production domain, and the guard renders null forever while it waits. Nothing throws, so the console is clean, and the page is blank in the most confusing way possible.

The tell is that the page is blank for logged-out visitors and fine for you, because your browser still holds a session from a previous deploy. Test in a private window. If signup and login behave inconsistently in production, login working while signup fails walks through the auth-specific side of this.

Cause 6: a crash during server rendering

On frameworks that render on the server, an exception during SSR can produce an empty document rather than an error page. Browser-only APIs are the usual trigger: window, localStorage, or document referenced at module top level rather than inside an effect. The server has no window, the render throws, and the response body arrives with nothing in it. Your host's function logs have the real stack trace.

Symptom-to-cause map

Make the next one visible

The only permanent fix for white screens is refusing to have them. Three cheap changes:

1. A root error boundary with a real message and a reload button. Ten lines, and it retires the entire failure mode.
2. Source maps uploaded to an error tracker. Sentry or an equivalent turns column 40218 into a file and line, and tells you the error happened before the user emailed you about it.
3. A post-deploy smoke check that loads the production URL in a headless browser and fails the pipeline if the root element is empty. This catches the white screen in CI rather than in front of a customer.

If your app also behaves differently on your machine than on the host in other ways, the broader pattern is worth reading up on in why apps work locally but not in production.

Frequently asked questions

Why does the white screen only happen in production and never locally? Development servers are forgiving in ways a production build is not. They serve unminified code, tolerate type errors, load environment variables from a local file, and skip the build step entirely. The fastest way to reproduce a production-only white screen is to run a production build locally and serve it, rather than using the dev server — most of these bugs appear immediately.

The console is completely empty. Now what? An empty console means nothing threw, so your app is rendering null deliberately. Open React DevTools and look at the component tree: you will usually find a layout or route guard mounted with no children beneath it, waiting on a session or a feature flag that never arrives.

Can I just roll back and figure it out later? Yes, and you should if customers are affected. Roll back to the last known-good deploy first, then debug the broken build in a preview environment. Debugging in production with a white page live is a self-inflicted deadline.

---

If your production URL is showing a white screen right now and the minified stack trace is not telling you anything useful, that is a solvable problem — usually within a couple of hours. SprintX diagnoses and fixes production failures in AI-generated and hand-written apps, then adds the error boundaries and monitoring so the next one announces itself. Send us your repo or deploy URL.