Your Bolt app deployed. Then it broke — what happened?
Bolt publishes your app through Netlify, and that handoff is where most breakage lives: environment variables that exist in the editor but were never added to the Netlify site, a Supabase connection that was never claimed, a fork that silently dropped the deployment, or an edge function rejecting webhooks because JWT verification is still on. The checks below cover each, with the official fix.
The editor and the deployment are different machines
In the editor, Bolt runs your app inside WebContainers — Node.js in your browser tab. Publishing hands a build to Netlify, a real host with its own settings, its own environment variables, and its own relationship to your Supabase project. Everything the browser-machine knew but the Netlify-machine doesn't is a production incident waiting for its first visitor.
Eight ways a Bolt app breaks — symptom, then fix
Works in the editor, broken on the published site
Symptom: The bolt.new preview is fine; the netlify.app URL errors or renders nothing.
Fix: Treat the deployed site as a separate machine. Open the live URL's browser console for the first real error, then check the Netlify deploy log. Most divergence is configuration that never left the editor — env vars (next check) and the Supabase connection are the usual suspects. If you switched hosting, unpublish first; Bolt requires it before changing providers.
Environment variables missing on Netlify (community-reported)
Symptom: API calls fail or the app initializes empty on the live site only.
Fix: Bolt's docs don't promise env vars transfer to your Netlify site — and the most community-reported fix is adding them yourself: Netlify → Site settings → Environment variables, then redeploy. For Supabase edge-function secrets, add them in Supabase → Edge Functions → Secrets, then prompt Bolt to refresh its connection so it picks them up.
Supabase not connected — or the database never claimed
Symptom: Database reads/writes fail everywhere, or auth refuses to initialize.
Fix: Per Bolt's docs the most common causes are an unconnected Bolt account or an unclaimed Bolt-created database. Disconnect and reconnect Supabase in Settings → Applications, and claim the database in Supabase. Note the documented limitation: Supabase connections work with Vite projects only — not Next.js.
Data loads for you but not for users (RLS)
Symptom: Tables look fine in Supabase, but the app shows empty lists.
Fix: Bolt's troubleshooting lists RLS misconfiguration as a known Supabase issue — reset and reapply the rules through Bolt. The mechanism is Supabase's: with RLS enabled and no policy granting access, queries return empty results with no error.
Stripe (or any) webhooks rejected by your edge function
Symptom: The provider's dashboard shows failed deliveries; nothing fires in your app.
Fix: Supabase edge functions verify a Supabase JWT by default — third-party webhooks don't carry one. Bolt's docs say to disable JWT verification for webhook-receiving functions and validate a secret or signature header from the provider instead (for Stripe, the signing secret). Then replay a test event from the provider's dashboard.
Fork or duplicate silently lost your deployment
Symptom: After forking, publishing creates a brand-new URL — or the custom domain errors.
Fix: Documented behavior: forking/duplicating loses the Netlify connection and creates a new Netlify site. "Another project is already using this domain" means the domain is still attached to the old deployment — detach it there, attach it to the new site, republish.
The editor itself misbehaves (WebContainers limits)
Symptom: Preview won't boot, runs out of memory, or breaks only in one browser.
Fix: Bolt runs on StackBlitz WebContainers — Node.js inside your browser. Full support is Chromium-only (Firefox/Safari are beta), large projects can hit memory limits, and blocking third-party cookies/storage can break the required service worker. Try Chrome with site data allowed before assuming your app is broken.
An API key shipped to the client
Symptom: A scanner, a stranger, or your provider's usage page says your key is public.
Fix: Rotate first, investigate second. Bolt's official guidance: rotate keys regularly, remove unused keys, never store secrets in plain text. Supabase: create a new secret key (Settings → API Keys), swap, delete the old one — deletion is irreversible. Stripe: roll immediately on suspicion. Then move the call server-side so the key lives in secrets, not the bundle.
Paste this into your incident notes
Bolt app triage
[ ] Open the LIVE netlify.app / custom-domain URL in incognito; read the console.
[ ] Netlify deploy log: did the last publish build clean?
[ ] Netlify -> Site settings -> Environment variables: every var the app needs exists.
[ ] Supabase connected in Bolt (Settings -> Applications)? Database claimed in Supabase?
[ ] Supabase edge-function secrets set? Prompted Bolt to refresh the connection?
[ ] Webhooks: JWT verification OFF for webhook functions; signature/secret validated instead.
[ ] Forked recently? Check for a NEW Netlify site; move env vars + custom domain to it.
[ ] RLS: policies grant real users access; empty lists usually mean missing policies.
[ ] Any key in the client bundle: rotate it (Supabase secret key / Stripe roll), move call server-side.How Nightlamp catches this before your users do
Every check here runs against the deployed site, not the editor: an http_status check proves the Netlify URL (and your custom domain) answer at all, a browser_journey loads the live app and asserts real content rendered — blank screens and missing-env-var init failures both trip it — an api_canary reads through your Supabase-backed API the way a signed-in user would, which is what exposes unclaimed databases and RLS-empty tables, and an http_keyword probe on your webhook endpoint catches the JWT-verification rejection before your payment provider gives up retrying.
Bolt troubleshooting FAQ
Where is my Bolt app actually hosted?
On Netlify, via Bolt's integration — a random netlify.app URL (Bolt: Publish, Netlify: Deploy). Use the Claim URL to move the site into your own Netlify account. Bolt also offers built-in hosting and custom domain management.
Why is the deployed app blank when the editor works?
Official guidance covers the in-editor blank screen (refresh, read the console, paste errors into Bolt). On the deployed site, the most community-reported cause is env vars never added to Netlify — add them in Site settings → Environment variables and redeploy.
Why did forking break my app?
Forking loses the Netlify connection and creates a new site; custom domains stay on the old deployment until you move them. That's documented Bolt behavior, not a bug in your app.
Why doesn't Supabase data load?
Top documented causes: Bolt account not connected to Supabase, or the database never claimed. Reconnect under Settings → Applications. Vite projects only. If data loads for you but not users, it's RLS returning empty results.
A key leaked — how bad is it?
Treat any exposed secret key as compromised: rotate (Supabase: new secret key, then delete the old; Stripe: roll immediately), then move the call into a server function so the key never ships in the bundle again.
Want the fork-night surprise caught for you?
Point Nightlamp at your deployed Bolt URL and the flows your users actually run. When the live site diverges from the editor, you get the diagnosis — which variable, which connection, which deployment — not just a red light.
Start 14-day trial · no cardNewsletter
One real no-code incident + the fix, monthly
A post-mortem from a real no-code outage — what broke, how it was found, and the fix — once a month. Confirming also gets you the no-code incident runbook pack.
Double opt-in. One-click unsubscribe. No spam, ever.