White screen or 404 after you deploy (but it worked in preview)

One error, one plain-English fix you can paste into your AI tool. For React/Vite single-page apps (typical of Lovable and Bolt exports) deployed to Vercel or Netlify.
Last checked against official docs: 19 Oct 2026.

Symptom

• The homepage loads, but refreshing /dashboard or opening a direct link gives 404 Not Found.
• Or the deployed site is a blank white page, often right after login or on first load.

Why it happens (plain words)

There are two common causes.

A. Missing "send every page to index.html" rule (the 404). Your app has only one real page, index.html. The browser code then decides what /dashboard shows. The host doesn't know that: when someone requests /dashboard directly, it looks for a file with that name, finds none, and returns 404. Vercel's own guide says it "cannot infer that a project is an SPA" and you need a catch-all rewrite.

B. Missing environment variables (the white screen). Preview had your Supabase URL/key etc. The production host doesn't, because .env isn't uploaded. Vite variables are baked in at build time, so the app crashes at startup and shows nothing. A JavaScript error in the console is the giveaway.

How to confirm

1. Open the live site → DevTools → Console. Red errors like supabaseUrl is required, undefined, or Failed to fetch usually mean cause B.
2. Network tab: if the page request itself returns 404 on a deep link, it's cause A.
3. Check your host's project settings → Environment Variables: are all the VITE_... variables your app uses present?

Step-by-step fix

A. Add the SPA rewrite

• Vercel: create vercel.json at the repo root:

  { "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

  If you also have /api routes: "source": "/((?!api/).*)". If you use "cleanUrls": true, the destination must be "/index". Make sure the file is committed to Git. Don't do this for Next.js (use Next's own routing).

• Netlify: create public/_redirects (so it ends up in the build output) with:

  /*  /index.html  200

  Put it last if you have other rules.

B. Add the environment variables

1. List every import.meta.env.VITE_... your code reads.
2. Add each one in Vercel/Netlify → project → Environment Variables (for the Production environment).
3. Redeploy (env changes need a new build).
4. Only public values belong in VITE_ variables. See the exposed-keys guide.

Copy-paste prompt for your AI tool

My app works in preview but in production on [Vercel/Netlify] I get [404 on refresh / a blank white page].
1. Confirm whether this is a client-side routed SPA (e.g. React Router + Vite) or a framework with its own routing (Next.js etc.).
2. If it is a Vite SPA: add the correct catch-all rewrite file for [Vercel: vercel.json at repo root / Netlify: public/_redirects], excluding /api routes if any exist.
3. List every environment variable the frontend reads (import.meta.env.*), and tell me which ones I must add in the host dashboard. Flag any that look like secrets and must NOT be public.
4. Add a visible error message instead of a blank screen if a required env variable is missing at startup.
Explain what you changed in plain English.

How to verify it's fixed

• After redeploying, open `https://yoursite.com/some-inner-page` directly in a new tab, then refresh it. It should load.
• Console has no red errors on first load (logged out and logged in).
• Try one real action (login, load data) on production.

Safety notes

• Don't "fix" missing variables by hardcoding secret keys in code.
• A catch-all rewrite can hide real missing files. Check that images/assets still load.

Sources

• Vercel KB: Why is my deployed project giving a 404?, https://vercel.com/kb/guide/why-is-my-deployed-project-giving-404
• Vercel: vercel.json rewrites, https://vercel.com/docs/project-configuration/vercel-json
• Netlify: Rewrites and proxies (SPA rule), https://docs.netlify.com/routing/redirects/rewrites-proxies/
• Vite: Env variables and modes, https://vite.dev/guide/env-and-mode