Bolt.new Not Working? Fix the 10 Most Common Errors (2026)

Jump to your symptom: Bolt won't load · blank preview · preview stuck or out of memory · connect to Supabase · prompt too long · Bolt stuck or ignoring you · Bolt broke something · publishing fails · Netlify after duplicating · can't log in or projects missing

Before You Touch the Code: 4 Quick Checks

1. Check whether Bolt itself is having problems. Open Bolt's status page. If there's an active incident, wait for it to clear before changing anything.
2. Find out where it breaks. Is it the Bolt editor, the preview inside Bolt, or your published site? Each one has its own section below.
3. Suspect the last change first. If the app worked before Bolt's last edit, restore an earlier version before asking for more changes (Error 7).
4. Read the exact error. Open the browser console with Cmd+Option+J (Mac) or Ctrl+Shift+I (Windows), or look at the Terminal tab in Code view. Copy the red error text word for word.

Error 1 - Bolt.new Not Loading or "WebContainer Startup Error"

What you see: Bolt opens but the project never starts, the preview never appears, or you get a WebContainer startup error. Sometimes you see a 403 or 404 error.

Why it happens

Bolt runs your project inside your browser, using a technology from StackBlitz called WebContainers. That means your browser, its extensions, your VPN and your antivirus can all get in the way, even when nothing in your project changed.

How to fix it

1. Check status.bolt.new for an ongoing incident.
2. Use Chrome or another Chromium-based browser. Bolt's documentation lists this as a requirement for WebContainers.
3. Temporarily turn off browser extensions, especially ad blockers, and turn off your VPN. Then hard-refresh: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows).
4. Try Chrome Guest mode, which runs without your extensions and saved data. If Bolt works there, an extension or cached data is the cause: clear your browser cache and turn extensions back on one at a time.
5. If you see a 403 or 404 error, check whether your antivirus is blocking Bolt's files.

What you should see: the project opens and the preview starts. If the status page shows an incident, the only fix is to wait.

Error 2 - Bolt Preview Blank, White or Gray Screen

What you see: the preview pane is empty, or shows a plain white or gray screen, even after a refresh.

Why it happens

According to Bolt's documentation, a white screen can mean there's an error in your app that Bolt can't detect on its own. Missing environment variables are another common cause: environment variables are the settings and keys your app reads when it starts, such as your database address.

How to fix it

1. Open the browser console (Cmd+Option+J on Mac, Ctrl+Shift+I on Windows) and look for red error lines. Copy the exact text.
2. Switch to Plan Mode, where Bolt answers questions without changing your code: click the Plan button (it turns blue), then ask: "The app preview is showing a white screen. Review the project for runtime errors, missing dependencies, or configuration issues that could be preventing it from loading." Paste the console error too.
3. Open Code view (the <> icon), go to the Terminal tab and run npm run build. A build shows errors that don't always appear while you're building. For what those errors mean, see fixing Bolt.new build errors.
4. Ask Bolt: "List every environment variable and tell me where each value can be found so I can add them through the Secrets interface." Then add any missing ones in Secrets.

What you should see: the preview shows your app and the console has no red errors. If the blank screen started with Bolt's last change, restoring a version is faster (Error 7).

Error 3 - Preview Stuck on "Your preview will appear here" or "Out of memory"

What you see: the preview never loads and stays on the Your preview will appear here screen, or you get an Out of memory (OOM) error.

Why it happens

Bolt's documentation gives two separate causes. A preview stuck on the placeholder screen usually means a port conflict or an error that stops the preview from running. An out of memory error means your computer doesn't have enough free memory to run the project in the browser.

How to fix it

1. For a stuck placeholder, open Code view and read the Terminal tab. Copy the last error and ask Bolt in Plan Mode what stops the preview from starting.
2. For out of memory, close browser tabs you don't need, especially other Bolt or StackBlitz projects, and close other apps running in the background.
3. Refresh the page. If that doesn't help, restart your computer and open only this project.

What you should see: the preview loads your app instead of the placeholder, and the memory error doesn't come back while only one project is open.

Error 4 - Bolt.new Supabase Not Connecting (or Which Database You're Using)

What you see: you can't find how to connect Bolt to Supabase, the Supabase option isn't available on your plan, a database you claimed doesn't appear, or your app can't reach its data.

Why it happens

Many guides assume every Bolt app uses Supabase. Today Bolt has its own built-in database, Bolt Database, which works without any third-party account. Supabase is an option on the Pro and Teams plans. Knowing which one your project uses changes where you look.

How to fix it

1. Check your plan. Connecting a Supabase database requires a Pro or Teams plan.
2. To connect Supabase: in any project, click the gear icon (top center), select All project settings, open Applications under Account, and click Connect in the Supabase row. Log in to Supabase, choose your organization and click Authorize Bolt.
3. If your project already has data in Bolt Database, don't just connect a new Supabase database. Bolt warns that replacing the connection may cause data loss. Instead, claim your current Bolt database in Supabase so the data comes with it.
4. If a claimed database doesn't appear, disconnect and reconnect Supabase in Settings > Applications.
5. If the app loads but shows a blank screen or database errors, ask Bolt to list the environment variables it needs (Error 2) and check that none is missing.

What you should see: Supabase shows as connected under Applications, and your app reads and saves data in the preview.

Never paste a secret database key into the chat or into front-end code to "make it connect." Keep keys in Secrets.

Error 5 - "Prompt too long, or project exceeds total supported prompt size"

What you see: Bolt shows this message and won't take your next request.

Why it happens

Bolt reads your project along with your request. When the project gets too big, with many files, long files or leftover documents, it no longer fits.

How to fix it

1. Back up first: Project title > Export > Download. Some of the steps below delete files.
2. Ask Bolt: "Remove any unused files and components." Delete Markdown files you don't need.
3. In the Terminal, run npx knip --production --fix --allow-remove-files to remove unused code and files.
4. Run npx depcheck to find unused dependencies, and npm dedupe to remove duplicate package versions.
5. Ask Bolt to split any file over about 700 lines into smaller files.

What you should see: Bolt accepts your request again. Check the preview after the cleanup, because removed files can break something that was still in use. If it does, restore the version from before the cleanup (Error 7).

Error 6 - Bolt Stuck, Not Responding or Not Doing What You Asked

What you see: Bolt stops responding, keeps going around in circles, or only does part of what you asked.

Why it happens

Big prompts with several changes at once can overwhelm Bolt, and a long conversation keeps a lot of old context around.

How to fix it

1. If Bolt is stuck, type /clear in the chat box and select Clear context.
2. Ask for one change at a time. Check it works in the preview before asking for the next one.
3. For bigger features, use Plan Mode first so Bolt lays out a plan before it writes code.
4. Keep a README.md that describes how your project is organized, and point Bolt to it after using /clear.

What you should see: Bolt responds again and completes one small change at a time. If each attempt breaks something new, stop and restore a working version (Error 7).

Error 7 - Bolt Broke Something That Worked

What you see: after Bolt's last change, a feature that used to work is broken, and asking it to fix things makes it worse.

Why it happens

Each change can touch many files. Asking for fix after fix on top of a broken state piles up more changes instead of undoing the one that caused the problem.

How to fix it

1. Stop asking for new fixes.
2. Click the Version history button (the clock icon) in the top menu.
3. Select the last version from before the problem and check the preview that loads.
4. Click Restore this version in the top-right, then confirm with Restore version.
5. Ask for the change again in smaller steps.

What you should see: a success message in the chat and the app working as it did in that version.

Important: restoring an earlier version does not change your Bolt or Supabase database. If the broken change also altered your data, restoring the code won't undo that part.

Error 8 - Bolt Publishing Fails or the Live Site Won't Open

What you see: one of these two messages:

• Project is too large to deploy. The maximum allowed size is 100MB.
• This site can't provide a secure connection, with ERR_SSL_PROTOCOL_ERROR, when you open your published site.

Why it happens

The size error usually comes from large images or videos stored inside the project. The secure connection error usually comes from the network you're on, not from your app.

How to fix it

1. Too large: download the project and check the folder size on your computer. Ask Bolt to find and delete images or videos you don't use.
2. Move the media you do need to external storage, such as Supabase Storage, Cloudflare R2, AWS S3 or Google Cloud Storage. Then ask Bolt to use those web addresses instead of the files in the project, and remove the files. More detail in fixing Bolt.new "too large" errors.
3. Secure connection error: open the site on another network, such as your phone's hotspot. If it works there, add .bolt.host to your router's list of trusted domains.

What you should see: publishing finishes, and your site opens at its .bolt.host address or your own domain.

Error 9 - Bolt Failed to Publish to Netlify, or Lost Netlify After Duplicating

What you see: publishing to Netlify fails, or after you duplicated or forked a project, it's no longer connected to your Netlify site and your domain doesn't show the new version.

Why it happens

Netlify is an optional hosting integration. Duplicating or forking a project cuts its Netlify connection, and reconnecting creates a new Netlify site.

How to fix it

1. If publishing to Netlify keeps failing, run the build command yourself and deploy manually with Netlify's drag-and-drop deploy.
2. After duplicating, reconnect the project through the Netlify integration. This creates a new site.
3. Move your custom domain to the new site, either in Netlify or in your domain provider's settings.

What you should see: your domain shows the latest version of the duplicated project.

Error 10 - Bolt.new Login Not Working or Projects Missing After Signing In

What you see: you can't sign in, you get There is already a user associated with this email, or you sign in and the projects you expect aren't in the list.

Why it happens

According to Bolt's documentation, the "already associated" error comes from signing in with different providers, such as GitHub and Google, that use the same email. Missing projects usually mean you're in a different workspace or signed in with a different account.

How to fix it

1. "Already associated with this email": sign in to StackBlitz with the provider you first used (for example GitHub), click Settings, open the Credentials tab and click Add Google credentials, or add GitHub credentials if you started with Google.
2. No confirmation email: click Resend confirmation email on the Bolt sign-in screen.
3. Forgotten password: click Forgot password? on the sign-in screen. If you sign in with GitHub or Google, reset the password with that provider instead, then sign in to Bolt with the same provider.
4. Projects missing: open the account menu in the left sidebar and check which workspace has the checkmark. Switch if needed.
5. Check that the email address in the account menu is the one you signed up with.
6. Sign in to StackBlitz and look in Collections > Bolt collection.
7. If the projects aren't anywhere, contact support@bolt.new.

What you should see: you're signed in and your projects are in the list. To avoid depending on one account in future, export a copy from time to time (Project title > Export > Download) or connect the project to GitHub.

What Bolt.new Actually Does (Common Misunderstandings)

• Not every Bolt app uses Supabase. Bolt has its own database, Bolt Database. Supabase is optional and needs a Pro or Teams plan.
• Restoring a version doesn't restore data. Version history changes your code, not your Bolt or Supabase database.
• Bolt Hosting addresses end in .bolt.host. There is no bolt.new.app domain, so any guide that mentions one is wrong.
• Bolt's Stripe integration needs Supabase, and it already checks webhook signatures. The integration requires Supabase as your database. Bolt creates Supabase Edge Functions and registers the Stripe webhook with signature verification included, so "add signature checking" is not the usual fix when payments don't update your app.
• The preview runs in your browser. That's why browser extensions, VPNs and low memory can break it.

When It Isn't a Bug

• The 100MB publishing limit is a platform limit. Large media has to live outside the project.
• Connecting Supabase requires a Pro or Teams plan. That's a plan requirement, not an error.
• There's currently no supported way to move a Supabase database back into Bolt Database, so choose carefully before switching.
• If the app works in Bolt and only fails for real users on the live site, the builder is fine and the issue is in production settings. See Bolt.new preview vs production errors.

What to Include When You Ask for Help

Whether you ask Bolt, Bolt support or a developer, include:

• Where it breaks: the Bolt editor, the preview, publishing, or the live site.
• The exact error text from the browser console or the Terminal tab, copied word for word. This matters most for vague messages like a 500 or "something went wrong."
• When it last worked, and what changed since.
• Which database the project uses (Bolt Database or Supabase) and where it's published (Bolt Hosting or Netlify).
• Your browser, and whether it happens in Chrome Guest mode too.
• The names of your Secrets, never their values.

Frequently Asked Questions

Still broken after this guide?

If your Bolt.new app keeps failing in ways this guide doesn't cover, the AppStuck Master Prompt gets your AI builder to write up the problems in your app, so you can see what's wrong before you change anything else. It's free. Get the Master Prompt.

Sources

• Bolt support: Preview issues (verified 25-sep-2026)
• Bolt support: Bolt issues (verified 25-sep-2026)
• Bolt support: Publish issues (verified 25-sep-2026)
• Bolt support: Login issues (verified 25-sep-2026)
• Bolt support: Plan Mode (verified 25-sep-2026)
• Bolt support: Database (verified 25-sep-2026)
• Bolt support: Supabase for databases (verified 25-sep-2026)
• Bolt support: Backups, restore, and version history (verified 25-sep-2026)
• Bolt support: Hosting (verified 16-sep-2026)
• Bolt support: Stripe for payments (verified 25-sep-2026)
• Bolt status page