White Screen After Deploy? A Debugging Playbook

The app worked perfectly on your machine. You deployed it, opened the URL, and got a polite expanse of nothing. This is one of the most common failure modes for AI-built apps, and the reassuring part is that a blank page is rarely mysterious — it's almost always one of a handful of causes, and the browser will tell you which if you know where to look. Work down this list in order. Most white screens die in the first two checks.

Step one: open the browser console before touching code

Open DevTools (F12, or right-click → Inspect), switch to the Console tab, and reload the page. A blank single-page app almost always shows either red JavaScript errors or failed network requests there. Then check the Network tab and reload again: scan for red rows — requests coming back 404 or with an unexpected content type. Copy those messages; they are the diagnosis, and they're precisely what you'd hand to an AI agent to fix. Everything below corresponds to a specific signature you might be staring at.

Wrong asset paths after the build

Bundlers rewrite imports into paths like /assets/index-a1b2c3.js, absolute from the site root. Deploy into a subdirectory — GitHub Pages under /repo-name/, or anything served behind a base path — and the browser requests /assets/... from the domain root instead, gets a 404 or, worse, an HTML error page standing in for JavaScript, and renders nothing. Signature: Network tab full of 404s on hashed filenames. Fix: set the bundler's base path (Vite calls it base; other tools have equivalents) to match where the app actually lives, rebuild, and redeploy.

Stale cache serving dead bundles

Hashed filenames change on every build, but index.html usually keeps its name. If a CDN, host, or your own browser serves a cached copy of that HTML, it references JavaScript files that no longer exist on the server — blank page. Signature: 404s on chunk names you don't recognize from the current build, or the site loads fine in a private window but not normally. Fix: purge the CDN cache, make sure the host sends short cache lifetimes for HTML while only hashed assets get long-lived caching, then hard-reload. This bites hardest right after rollbacks and rapid redeploys.

Missing SPA fallback routing

Single-page apps fake their URLs client-side. Open a nested route directly — /dashboard/settings — by typing it, refreshing on it, or following a deep link, and the server goes looking for a literal file that was never built. Many hosts return their 404 page; some return something emptier. If the homepage loads but deep links blank out or error, this is your cause. Fix: configure the host to rewrite all unknown paths to index.html. Every mainstream static host supports this under some name — rewrite, fallback rule, or single-page-app mode.

MIME types and strict module loading

Modern bundles load as ES modules, and browsers enforce the content type strictly: a .js file served as text/plain or text/html gets refused outright, sometimes killing the whole app silently. Signature: a console error about MIME type or "Failed to load module script." This typically happens when a host misconfigures content types, or when a soft-404 HTML page is returned with a 200 status in place of the script. Fix: serve static files from hosting configured to send proper JavaScript content types, and confirm the failing URL actually returns code rather than an error page wearing a success status.

Environment variables baked in at build time

Frameworks like Vite inline VITE_-prefixed variables into the bundle at build time, reading them from your local shell or .env file. Deploy that same build elsewhere without the values set, and code referencing them gets undefined: API calls aimed at nowhere, auth that never initializes, blank screen. Signature: console errors mentioning undefined configuration, or network requests to malformed URLs. Fix: set the variables in the deploy environment's build step and rebuild there — these values must exist when the bundle is produced, not just at runtime.

Hand the evidence to an agent

Once the console output exists, this stops being a mystery and becomes a fix request. Paste the console errors and Network failures into an agent session and let it trace the cause — reading your config, reproducing the build, and verifying its own fix is exactly the loop described in what is agentic coding. And if the deploy pipeline itself is what you don't understand yet, start from how to deploy an app built with AI instead of guessing at hosting settings one toggle at a time.

The meshcode angle

meshcode is a native desktop app for Mac and Windows where each pane runs its own agent session over the same repo — one pane digs through build config while another checks deployed assets and response headers, neither blocking the other. Bring the Claude Code or Codex CLI subscription you already have, or start with meshcode's own models billed pay-as-you-go with no monthly fee.

👉 Download meshcode — Mac, Windows