Your Bolt.new app works in preview and breaks deployed

Updated 2026-08-27 · MateValidate

In the Bolt preview everything works. You deploy — to Netlify, Vercel, or with Bolt's own button — and the live site is blank, half-working, or erroring on everything it touches.

The mental model that makes this fixable: the preview and the deployed site are two different machines. The preview runs inside Bolt's environment, with Bolt's environment variables, Bolt's integrations, and Bolt's URLs attached to it. Deploying copies your code to another machine. Everything the code was taking from the environment — keys, URLs, connections — stayed behind.

So the question is never "why is the deploy broken", it is: which of the four things below did the code silently depend on?

First: get the real error, from the real site

Open the deployed URL, press F12 → Console, and reload. Also click the Network tab and look for red rows. Every failure below announces itself there with a specific message, and that message is what your AI needs — not "it doesn't work deployed".

1. Environment variables did not travel

The most common one by a distance. The symptom is a crash or empty data right on load, and console lines like:

Uncaught Error: supabaseUrl is required.
TypeError: Failed to construct 'URL': Invalid URL

Fix, in this order:

1. In your host's dashboard, add every variable the app needs — Netlify: Site configuration → Environment variables; Vercel: Settings → Environment Variables.
2. Copy the names exactly as the code reads them, prefix included (VITE_SUPABASE_URL, not SUPABASE_URL) — the prefix decides whether the build can see it at all.
3. Trigger a new deploy. Frontend variables are inlined into the JavaScript at build time; changing them without rebuilding changes nothing. The mechanics are in the env variables guide.

2. A URL that only exists in the preview

Search your code for localhost, 127.0.0.1, and webcontainer — Bolt's preview happily serves an API on a local port, and the deployed frontend then tries to call an address that exists on no machine but yours. The console shows:

TypeError: Failed to fetch
net::ERR_CONNECTION_REFUSED

The fix is to put the API's real deployed address in an environment variable rather than swapping one hardcoded URL for another — otherwise the same failure returns on the next environment. If the console mentions CORS instead, that is a different failure with its own guide.

3. Pages 404 when refreshed or opened by link

The home page works; refreshing /dashboard, or sending somebody a deep link, shows the host's 404 page. Nothing is broken in your app — the host just needs to be told that a single-page app serves every route from one file. It is a two-line fix that depends on the host, covered in the SPA refresh guide.

4. The integration was never claimed by the deployed site

Bolt wires integrations (Supabase above all) into its environment. The deployed site needs the connection to exist on its side: the database URL and anon key present as variables on the host, and — if you duplicated or remixed the project — a fresh connection, because integrations do not follow a copy. If the console shows 401 / 403 responses from *.supabase.co even though the keys are set, the database is refusing the request itself — that is a row-level security problem, not a deployment problem.

Hand it to the AI properly

My Bolt.new app works in the preview but fails deployed to [Netlify/Vercel].
The first console error on the deployed site is:

[paste the exact error]

The failing network request, if any, is:

[method, URL and status from the Network tab]

Check, in this order: environment variables the code reads but that are not
set on the host; hardcoded localhost or preview URLs; missing SPA redirect
configuration; a Supabase connection that is not configured for this deploy.
Tell me the exact variable names and host settings to add, then what to
redeploy.

Then prove it

After redeploying, open the deployed URL in a private window with the console open. Working means the flows work and the console stays clean — a site can render while still failing half its requests, and the person who finds those is usually not you.