Bolt.new breaks your app with every change? How to stop it
Why each Bolt.new prompt can break features that worked, what to do the moment it happens, and a routine of locks, versions and tests that stops regressions.
Leer en español →
Bolt.new breaks working features because each prompt lets the agent rewrite code it can only partly see and doesn't fully remember, and nothing checks afterwards that the old features still work. You stop it by changing one thing per prompt, locking files that already work, writing your rules into project knowledge, keeping bookmarked versions to return to and testing a short checklist after every change. When something breaks, restore the last good version instead of prompting "fix it" again.
This guide explains why regressions happen, what to do in the first five minutes after one, and a routine that makes them rare.
Why does Bolt break things that worked?
A few causes account for most of it:
- The agent forgets. Bolt keeps recent messages in context and drops older ones. A decision you made twenty prompts ago ("keep the old checkout") may simply not be there anymore.
- Big files get rewritten whole. When a 1,500-line page handles five features, changing one means regenerating code around the other four.
- Logic exists in two places. After many fix attempts, the same rule (who can see an invoice, how a price is calculated) can live in two components. The fix lands in one and the other keeps the bug.
- Vague prompts invite wide changes. "Make the dashboard better" gives the agent permission to touch everything on that screen.
- Repeated auto-fixes pile up. Each Attempt fix changes more code based on a guess, and Bolt's own docs advise against clicking it over and over.
- Database changes aren't undone with the code. Version history restores files, not tables. If a change altered the database, rolling back the code can leave the two out of step.
What should I do right after something breaks?
- Stop prompting. Every new attempt makes the difference between "working" and "now" bigger and harder to read.
- Restore the last good version. Click the clock icon in the top menu to open version history, select the version from before the change, check the preview, then Restore this version. It doesn't use tokens.
- Check the database. If the broken change created or altered tables, the restore didn't undo that. Look at the tables in the database settings before you go further, and read our guide to changing your database safely in Bolt.
- Redo the change in a smaller step, using the prompt pattern below.
How do I stop regressions from happening?
Keep a five-minute smoke test
Write down the flows that must always work, and run through them after every change that touches more than text or colors. For example:
| Flow | What "working" means |
|---|---|
| Sign up and sign in | New account receives the email, can log in, lands on the dashboard |
| Main task | Create, edit and delete the core record (an order, a booking, a project) |
| Permissions | A second test user can't see the first user's records |
| Payment | Test card completes checkout and the account is upgraded |
| Mobile width | The main screen is usable at phone size |
Five minutes of clicking catches most regressions before your users do.
Bookmark versions that work
In version history, hover over a version and use Bookmark, or rename it ("payments working, Oct 20"). When something breaks two days later, you know exactly where to go back to.
Lock what's finished
In Code view, right-click a file and choose Lock file, or Lock all for a folder, so Bolt leaves it alone. Lock the auth setup, payment handlers and anything else you've tested and don't want rewritten. Use Target file to point Bolt at the one file you do want changed.
Write the rules down once
Put standing rules in Project settings > Knowledge, or in an agents.md file, which Bolt reads automatically and which survives clearing the context. Bolt's skills feature can hold reusable instructions too. Useful rules are concrete:
- Never change authentication, payments or database schema unless the prompt says so.
- Don't rename or delete existing database columns.
- Keep each component under 400 lines; create a new file instead.
- After any change, list every file you modified.Prompt for one change, with boundaries
Compare "fix the booking page" with:
In BookingForm.tsx only: when the date is in the past, show the error
"Choose a future date" under the date field and disable Submit.
Don't change any other file. Don't change the layout.The second one says which file, what to do, what not to touch and how you'll check it. For anything that spans several screens, start in Plan mode, agree on the steps, then build them one at a time.
Split the files that keep breaking
If the same file is involved in most regressions, it's probably too large. Ask Bolt to split it into smaller components, keeping the original as a thin wrapper, and test after each split. Bolt's help center suggests refactoring files around 500 lines or more.
Add automated tests once the app has users
A smoke test done by hand stops scaling at some point. Unit tests (for example with Vitest) for the rules that matter, such as prices, permissions and date logic, can run in the terminal with one command before you publish. End-to-end tests with Playwright are better run on your computer or in GitHub Actions. Our guide to tests for AI-generated code explains where to start.
Use a GitHub branch for risky work
With GitHub connected, create a branch from the GitHub menu in Bolt before a big change. If it goes wrong, switch back to main. Merging happens on GitHub, which also gives you a diff of exactly what changed.
When is it more than a prompting problem?
If the same bug comes back three times, fixing one screen breaks an unrelated one, or you find the same function written twice, the issue is the structure of the code, not your prompts. At that point a cleanup (removing duplicates, separating data access from screens, adding tests around the core rules) is cheaper than another week of patches. Our post on whether to rewrite or fix an AI-built app helps you decide how far to go.
Quick answers
Does restoring a version cost tokens? No. Version history restores are free, unlike asking Bolt to undo a change.
Will restoring a version undo database changes? No. Bolt's version history documentation says restoring an earlier version doesn't change your Bolt or Supabase database.
Should I switch to the Max agent to avoid regressions? It reasons more on complex, interconnected changes, but it can't remember what it never saw. Clear prompts and locks matter more.
How often should I bookmark a version? After every feature you've tested and are happy with.
Tired of fixing the same thing twice?
The free health check is a quick first look at the live app. If regressions keep coming, our Bolt app rescue finds the structural cause and prices each fix up front, and a maintenance plan keeps someone watching after each release. You can also describe what keeps breaking.
