How to fix a broken Bolt app (and when to get help)

A Bolt app that has stopped working has usually not failed all at once. One change broke something, the next prompt patched the symptom, and a few rounds later nobody, human or AI, can say which change did what. This guide is the order we work in when a founder sends us a Bolt project, written so you can do most of it yourself: get back to a version that works, read the actual error, get a copy of the code you control, fix the usual causes, and run a security checklist built for Bolt's stack before real users arrive.

Facts about Bolt here come from Bolt's own help center (support.bolt.new) as of October 2026. Bolt changes often, so if a button has moved, check the current docs.

First, get back to a version that worked

Prompting from a broken state builds on the breakage. Open Version history, click an earlier version to preview it, and choose "Restore this version". Bolt's documentation notes that rolling back this way costs no tokens, which prompting your way back does not.

Two cautions. Restoring a version does not change your Bolt or Supabase database, so if a later version added a table or column, the restored code may now meet data it does not expect. And if Bolt's security audit made fixes after the version you restore, those fixes go too; Bolt suggests describing the changes you want to keep in the chat instead of reverting past them.

Read the actual error

Bolt's troubleshooting guide is direct about this: retrying the same prompt is unlikely to help, and the exact error helps Bolt far more than a general description. There are four places to look.

• The terminal inside Bolt. Look for red text, select it, copy it into the chat. Asking Bolt to run a build also surfaces compile errors that never appear while the preview is running.
• The browser console. Ctrl+Shift+I on Windows, Cmd+Option+J on a Mac. Reproduce the problem and copy the first error.
• The database logs. Click the database icon at the top of the screen, then Logs, and choose a type: Server Function for your back-end code, Authentication for sign-in problems, PostgreSQL for failed queries, PostgREST for requests the app made to the database.
• The environment variables. A white screen often means a required variable is missing. Ask Bolt to list every variable the project needs and check each one is set.

Then switch to Plan Mode, which makes no code changes, and ask Bolt to explain the cause and propose a fix. Approve one change, check it, then make the next. If the preview itself misbehaves, Bolt's checklist is to use Chrome or another Chromium browser, clear the cache, turn off extensions such as ad blockers, and switch off any VPN.

Get a copy of the code you control

Connect the project to a GitHub repository in your own account, or download it as a ZIP. Two details of Bolt's GitHub sync matter before anyone else touches the code. Bolt looks for changes about every 30 seconds and, if both sides changed, overwrites the GitHub side. And disconnecting the repository cannot be undone without Bolt's support. So agree who edits where: while a developer works in GitHub, nobody prompts in Bolt, and the other way round.

The problems we find most often

These are the causes behind most Bolt projects that reach us, roughly in order of what they cost if missed. The Bolt page has a one-paragraph version of each.

1. Tables anyone can read or change

A Bolt app's browser code talks to its database directly, so the database's own access rules, called row-level security (RLS), are the only thing between a visitor and your tables. Bolt's documentation says it plainly: a table without RLS can be read and changed by anyone.

Bolt gives you a check for this on every plan. Click the database icon, then Security. It runs the same checks as Supabase's Security Advisor and labels each finding Error, Warning or Info. The two that matter most are a table without RLS and "RLS Policy Always True", a policy with no condition at all. "Ask Bolt to fix" will propose changes, but first decide for each table what it should be: readable by visitors, open for submissions, or private. Private data needs sign-in in the app first, then policies that limit each row to the user it belongs to.

If your project uses your own Supabase database, its SQL editor will list tables with RLS off:

select tablename
from pg_tables
where schemaname = 'public' and rowsecurity = false;

A clean scan is not proof. Sign in as one test user and try to read and change another test user's records, from the app and from the browser console. Our row-level security note covers the policies that pass a scan and still check the wrong thing.

2. Keys written into the front end

Bolt keeps API keys in Secrets (database icon, then Secrets), which your server functions read so that, in Bolt's words, private information never ends up in your users' browsers. The leak happens when a key goes into the front-end code instead, often pasted into a prompt to make an integration work. Anything in front-end code is downloaded by every visitor.

Treat any key that was ever in front-end code or the chat as public. Create a new one with the provider, revoke the old one, store the new one in Secrets, and move the call that uses it into a server function. Only the project owner (and, on teams, co-owners and admins) can manage secrets, which is worth knowing before a contractor asks for access.

3. File storage left public

Bolt Cloud storage buckets are public or private. Public means anyone with the link can see the file without signing in; private means only the people your RLS policies allow. Bolt says it is designed to create private buckets with policies for user uploads, and also says to confirm a bucket's visibility yourself, especially one you created or changed by hand. For anything personal, keep the bucket private and serve files through signed URLs that expire.

4. Sign-in links that go to localhost

New Bolt projects start with localhost:3000 as the authentication Site URL, which cannot work for a live app. Bolt usually updates it when you publish, but not always, especially with more than one domain. Confirmation emails and password resets can only send people to addresses on the redirect allow list; anything else falls back to the Site URL. Set the Site URL to your live address, add every domain and path users return to, including the password-reset page, and test the whole loop from a fresh private window.

While you are in the authentication settings, decide whether new users must confirm their email address, and turn on leaked password protection, which Bolt's security check flags when it is off.

5. Payments tested only on the happy path

Bolt's native Stripe integration needs a Bolt or Supabase database, sign-in, and server functions; it does not work with Firebase. It registers the webhook endpoint and verifies Stripe's signatures for you, and payment processing runs server-side. What it cannot decide for you is who gets access, so test more than one successful card. Bolt's guide lists Stripe test cards for a success (4242 4242 4242 4242), a decline (4000 0000 0000 0002) and a payment that needs extra authentication (4000 0025 0000 3155). Run all three with test keys, which start sk_test_, then cancel a subscription and check that access ends.

Bolt's Stripe page does not cover switching to live keys, so treat going live as a step of its own: change the keys, make one small real purchase with your own card, and confirm in Stripe's dashboard that the webhook event arrived and in your app that access followed it. If the project also has hand-written Stripe code from before the native integration, decide which path is live and remove the other.

6. A publish that fails, or a site some people cannot reach

Bolt's publish troubleshooting covers the common ones. "Project is too large to deploy" means the project is over 100 MB: move images and video to external storage such as Supabase Storage, Cloudflare R2 or Amazon S3, have Bolt reference the new URLs, and delete the local copies. "Could not find a build output directory" means the build did not produce a folder such as dist; paste the error into the chat and ask Bolt to fix the build, rather than prompting around it. An ERR_SSL_PROTOCOL_ERROR may only mean your network blocks .bolt.host addresses, so try the site on mobile data before changing any code. If publishing to Netlify fails, you can run the build, download the project and deploy it to Netlify by hand.

7. Code and database out of step

Because a restore leaves the database alone, a project that has been rolled back a few times often has tables nobody's code uses and code expecting columns that are gone. The lasting fix is to keep database changes as migration files in the repository, so the schema has a history alongside the code, and to keep a backup you have actually restored from.

A security checklist for a Bolt app before real users

On paid plans, start with Bolt's own security audit: click Publish, then "Run security audit". It reviews the code and the database, fixes what it can, and flags the rest; run from that button it uses no tokens, up to 30 times a day. Bolt recommends running it at least once before you publish and again after big changes. Then work through this list:

1. The database Security tab shows no table without RLS and no "RLS Policy Always True".
2. Signed in as user A, you cannot read, change or delete user B's records, from the app or the browser console.
3. Every storage bucket holding personal files is private, and files are served through signed URLs.
4. Every API key lives in Secrets and is used only in server functions; any key that was ever in front-end code or a prompt has been replaced.
5. The authentication Site URL is your live address, not localhost, and the redirect allow list includes the password-reset page.
6. Leaked password protection is on, and you have decided whether new users must confirm their email.
7. Stripe has been tested with a success, a decline and an extra-authentication card, plus a cancellation, before live keys go in.
8. The code is in a GitHub repository you own, and everyone knows not to edit in GitHub and Bolt at the same time.
9. Large media lives in external storage, keeping the project well under the 100 MB publish limit.
10. Someone checks the server function and authentication logs after launch, rather than waiting for a customer email.

When to get help

Call in an engineer when a problem survives a restore and a few careful, one-change prompts; before you take payments or store anything personal; or when a security finding is one you cannot explain in your own words. None of these mean starting again. Under Bolt is ordinary JavaScript, and most of what it built is usually worth keeping.

That is the work we do. A free 20-minute call tells you what we expect to find. The Quick Security Check ($495, in 48 hours) tests your published app from the outside for the problems above and tells you in writing what is exposed. How we fix Bolt apps, or see every price.