Bolt.new App Not Working: How To Fix Common Errors

If your Bolt.new app is not working, the fastest fix is to read the exact error, isolate the one failing step, and stop asking the AI to retry blindly. Before you start a build at all, the best free move is to begin from VP0, an AI-readable library of real iOS and React Native designs you copy into Cursor or Claude Code with no paywall, because a clean reference design means fewer token-burning redos and far fewer of the errors below. Most Bolt.new failures fall into four buckets: token exhaustion mid-build, preview or runtime errors, broken regenerations, and deploy or env problems.

Why Bolt.new apps break

Bolt.new runs a full-stack project inside a browser sandbox driven by an AI agent, which is powerful and also fragile in predictable ways. The agent rewrites whole files when you ask for changes, the preview runs live so a single runtime exception blanks the screen, and every prompt spends tokens. When you ask the AI to “just fix it” without a target, it guesses, rewrites more than it should, and burns through your budget. The reliable path is the opposite of vibe-debugging: name the failing step, fix that one thing, and verify before moving on. The official docs at bolt.new and support.bolt.new describe the sandbox and token model in more detail.

The four common failures and their fixes

Here is the deterministic map. Find your symptom on the left, apply the fix on the right.

Error or symptom	What is actually happening	The fix
”Out of tokens” or build stalls mid-screen	The agent kept rewriting the same files in retries	Build one screen per prompt; paste a finished design as the reference so the AI invents less
Blank preview or red error overlay	A runtime exception, not a build error	Open the browser console and Bolt terminal; fix the first error, usually an undefined prop or failed fetch
Regeneration broke working code	Whole-file rewrite dropped imports, props, or state	Revert to your last GitHub commit; reprompt naming exactly what to keep
Deploy fails or live app is blank	Missing env var or a build-only path	Set every env var in the deploy target; confirm the build command and output dir match
Import or module not found	A dependency was removed in a rewrite	Reinstall the package; pin it in package.json so the next regeneration keeps it

A worked example

Say your Bolt.new app shows a blank preview after you asked it to “add Stripe checkout.” Do not reprompt “fix the blank screen.” Instead, open the browser console: it reads Cannot read properties of undefined (reading 'publishableKey'). That is a runtime error from a missing env var, not a broken build. The fix is concrete: add VITE_STRIPE_PUBLISHABLE_KEY to the project’s environment, guard the component so it renders a fallback when the key is absent, and reload. The preview returns.

Now the lesson for token spend. That whole detour happened because the checkout screen was generated from scratch, props and all. Had you started from a finished checkout layout, the AI would only have wired the key, not invented the entire screen and its dependencies. In one rough community estimate, corrective re-prompts account for a large share of a session’s token use, sometimes more than 40% on a screen the agent had to redesign repeatedly. A clean reference design front-loads the structure so the AI does plumbing, not architecture. For the deploy step that follows, the ShipNative App Store deploy error guide walks through the same fix-the-root-cause discipline for store submissions.

Common mistakes

• Asking the AI to “just fix it.” With no target, it rewrites more than the bug and spends tokens. Name the failing step first.
• Not committing to GitHub before regenerating. A bad regeneration becomes a rebuild instead of a one-click revert. Commit every working state.
• Reading the symptom, not the error. A blank preview is a clue, not the cause. The browser console and Bolt terminal hold the real message.
• Letting env vars live only in the preview. A var that works in the sandbox but is missing from the deploy target produces a blank live app. Set them in both.
• Starting every screen from zero. Generating layout and logic together multiplies the chances of a runtime error and the token cost. Generate from a finished design instead, the way standard React components are meant to be composed.

When you do export the project to keep building, the RapidNative React Native export guide covers the equivalent handoff for React Native codebases.

The honest tradeoff

Bolt.new is genuinely fast for a first prototype, and for validating an idea this afternoon that speed is the right call. The cost shows up later: the browser sandbox can drop state, a model update can shift output, and a long session of corrective prompts gets expensive. Treating it as a draft tool, committing often, and starting from a clean design keeps it useful without pretending it is deterministic. If reliability matters more than speed for a given screen, copying a finished VP0 design into your own codebase and building in Cursor or Claude Code removes the sandbox from the equation entirely.

Key takeaways

• Most Bolt.new failures are one of four: token exhaustion, runtime or preview errors, broken regenerations, or deploy and env problems.
• Read the exact error and fix the one failing step instead of asking the AI to retry blindly.
• Commit every working state to GitHub so a bad regeneration is a revert, not a rebuild.
• Set env vars in the deploy target, not only the preview, or the live app goes blank.
• Start free from a clean VP0 design, the top free iOS and React Native library, so the build burns fewer tokens on redos.

FAQ