Bolt app works in preview but breaks when published: what to check
When a Bolt app works in the preview but breaks once published, the cause is usually one of six things: the live site was never updated, a route needs a redirect rule, the build output is not what Bolt hosting publishes, a value the browser needs is missing, the sign-in settings do not list the live address, or the database refuses the request. Check them in that order. The reason they differ is simple: the preview runs inside your browser, using StackBlitz's WebContainers (Bolt help, Preview issues), while the published site is a set of prebuilt files served from an address ending in bolt.host (Bolt help, Publish your project).
Check 1: is the live site up to date?
Bolt says changes to your project are not applied to your published site automatically. Open the Publish menu and click Update. Bolt notes that Publish and Update do not use tokens, while asking Bolt to publish in the chat does. Our advice: after updating, reload the live page with a hard refresh before testing again, so you are not looking at a cached copy.
Check 2: pages other than the home page say Page not found
A single-page app loads every page from index.html, so a direct visit or a refresh on an address such as /login finds no matching file. Bolt's fix is a redirect rule in a _redirects file, or in netlify.toml if the project has one: /* /index.html 200. Then click Publish, then Update (Bolt help, Publishing issues).
Check 3: the build does not produce what Bolt publishes
- Run npm run build in the Code view terminal. Errors that the preview tolerates can stop the production build.
- The message "Could not find a build output directory to publish" means the finished files went somewhere Bolt does not expect. Ask Bolt to check how the project builds.
- A message that the output contains no HTML file means a server-rendered framework such as TanStack Start, SvelteKit, Remix or Astro. Bolt hosting publishes prebuilt HTML, so Bolt's advice is to switch to SPA mode or prerendering and move code that needs secret keys into server functions. Bolt says Next.js is supported as it is.
- Projects must be under 100MB to publish. Move large images and videos to external storage.
Check 4: a value the browser needs is missing or out of date
Bolt keeps two kinds of value (Bolt help, Secrets). Environment variables live in the project's .env file and can be read by browser code, which means they end up in what is sent to every visitor. Secrets only work in server functions and never reach the published site. Bolt's preview help says missing variables can cause a white screen, and suggests asking Bolt to list the variables the project needs.
If your project uses Vite (look for a vite.config file in Code view), note how it treats these values. Vite only exposes variables that start with VITE_ to browser code, and it replaces them at build time (Vite, Env variables and modes). So if you change a value, the live site keeps the old one until you publish again. Vite also warns that VITE_ variables should not hold secrets such as API keys.
Check 5: sign-in does not know the live address
For a Bolt database, the authentication settings have a Site URL and a URI allow list (Bolt help, Database authentication settings). The Site URL defaults to localhost:3000, which Bolt says does not work for live apps. Bolt usually updates both when you publish, but you may need to edit them yourself if the app uses more than one domain. Add the bolt.host address, your custom domain and any password reset route. Google sign-in cannot be tested in the preview at all: Bolt says Google's sign-in flow blocks iframes, so test it on the published site. The same mechanism on Lovable is covered in Lovable login not working after you publish.
Check 6: the database refuses the request
Bolt's database help says tables are private by default and your app needs explicit permissions to read or write; ask Bolt to fix the permissions if you see a permissions error (Bolt help, Database issues). If the app is published through Netlify, Bolt can pause a low-usage database; Bolt says databases in live Bolt-hosted projects are not paused for inactivity. When you fix permissions, do not open the table to everyone. Our note on row level security mistakes explains what a safe rule looks like.
If it fails only for some visitors
If some people see "This site can't be reached" or a secure connection error, Bolt says a device, network or provider may be blocking DNS or bolt.host addresses, and that republishing will not fix it. Test on mobile data before changing anything.
Our own debugging habit
Open the live site with the browser console showing, reproduce the fault, and copy the first red error. It nearly always points to one of the checks above. Paste it into Bolt instead of describing the symptom, and change one thing at a time.
Still broken?
App Triage ($99 USD) gives you a written diagnosis and plan. The AI-Built App Audit ($299 USD) reviews sign-in, data access, exposed keys and payments. App Rescue and Move to Cloudflare covers stability, sign-in and security in its Rescue in place step for a fixed $999 USD. If the live site works but Google cannot find it, read why a Lovable or Bolt site is not showing in Google.
Sources
- Preview issues, Bolt help centre
- Publish your project to a live website, Bolt help centre
- Publishing issues, Bolt help centre
- Secrets, Bolt help centre
- Database authentication settings, Bolt help centre
- Database issues, Bolt help centre
- Env variables and modes, Vite docs