How to Debug Bolt.new Projects with Claude.ai

The Loop: What Happens When Bolt Can't Fix Its Own Code

Every Bolt user eventually encounters the loop. Bolt makes a fix. The fix breaks something else. You prompt again. Bolt fixes the new thing and re-breaks the original. Three, four, five iterations and you're further from working code than when you started.

The loop happens because Bolt's context has become polluted with conflicting information and failed attempts it can no longer reconcile. More Bolt prompts deepen the problem. The solution is stepping outside Bolt entirely for a fresh, objective diagnosis.

Claude.ai is the right tool for this.

When to Switch from Bolt to Claude

Switch when:

1. Bolt has attempted the same fix 3+ times without a lasting resolution
2. Each fix introduces a new unrelated bug
3. An error keeps appearing despite changes
4. Behavior contradicts what the code appears to do
5. Bolt's explanations of why something isn't working don't make sense

The earlier you recognize the loop, the less damage it's done.

The Diagnostic Package

Claude can't see your Bolt project. You transfer context explicitly with the diagnostic package:

I'm using Bolt.new to build [brief project description].

PROBLEM:
[Exact symptom — what you see vs. what you expect]

ERROR MESSAGE:
[Full error text including stack trace]

RELEVANT FILES:
[Paste the 2-4 files most involved in the problem]

WHAT BOLT HAS TRIED:
[List the last 3-5 fix attempts, in order]

QUESTION:
What is the root cause, and what is the minimal correct fix?

The "What Bolt has tried" section eliminates Claude from re-suggesting approaches that have already failed.

Common Problems and Claude's Diagnoses

UI Doesn't Update After Database Change

Symptom: Supabase mutation succeeds, but the component shows old data.

What to give Claude: The React Query hook, the mutation function, and the component. Describe what Bolt has already tried.

What Claude typically finds: A query key mismatch. The mutation invalidates key 'tasks' but the query uses key ['tasks', projectId]. The invalidation doesn't match, so the cache never refreshes.

---

Supabase RLS Returning Empty Results

Symptom: Authenticated user gets empty arrays or 403 errors on legitimate queries.

What to give Claude: The Supabase query, the RLS policy SQL, and confirmation the user is authenticated.

What Claude typically finds: Column name mismatch (user_id vs owner_id), policy applied to wrong operation (UPDATE instead of SELECT), or policy never enabled on the table.

---

TypeScript Errors After Bolt Refactor

Symptom: Build fails after Bolt changed a type definition or component interface.

What to give Claude: The full TypeScript error, the type definition, and the components/services using it.

What Claude typically finds: A new required field added to the type without being added to all the places that create objects of that type.

---

Analyzing a Long Bolt Chat History

If the conversation itself is the problem, export it and ask Claude:

Here is the recent Bolt.new conversation history for my project.
I'm experiencing [describe problem].

1. Where was the problem introduced?
2. What is the root cause?
3. What is the minimal fix?
4. What other issues exist that should be addressed separately?

[Paste conversation history]

Claude reads the conversation as a debugging trace and identifies exactly which prompt introduced a bad assumption.

Writing the Fix Back to Bolt

Once Claude provides a diagnosis, return to Bolt with a scoped instruction:

The root cause is [Claude's diagnosis].

Make the following specific change only:
[Exact change described]

Files to modify: [list them]
Do not refactor anything else.
Do not add new dependencies.
Do not make any changes beyond what's described.

Without "do not refactor anything else," Bolt may make additional improvements alongside the fix — obscuring whether the core fix actually worked.

After the Fix

1. Test the specific broken scenario
2. Test adjacent functionality for regressions
3. If it works, continue normally
4. If it doesn't, revert and return to Claude with updated failure data

Don't chase a second fix attempt in Bolt without re-running the diagnostic process. Claude needs to know what the first attempt tried and what happened.

Two AI Tools, Two Roles

Bolt builds. Claude diagnoses.

Bolt is optimized for implementation — project context, live runtime, rapid iteration. Claude is optimized for analysis — systematic reasoning through code without the constraint of an active session.

Used together, they cover each other's weaknesses. Bolt moves fast; Claude catches what Bolt misses. Neither is sufficient alone for complex builds.

For the full Bolt workflow — initial prompts, kiro files, sprint management, and best practices — read The Complete Guide to Bolt.new.