​
Tips to avoid issues

Before you start, try the following:

  • Use Chrome or a Chromium based browser.
  • Selectively disable browser extensions, especially ad blockers, to see if this resolves the issue.
  • If accessing Bolt through a VPN, try again with the VPN disabled.
  • Check if antivirus software is blocking Bolt assets, especially if you receive a 403 or 404 error.

​
White screen, grey screen, or no preview showing

Prompt Bolt:

The preview is not showing, please fix this.

This may resolve the issue in some but not all cases. If this doesn’t resolve the issue, repeated prompting won’t be successful. Don’t make repeated attempts, as this uses up tokens.

​
Prompt too long, or project exceeds total supported prompt size

You can use the following methods to reduce the size of your project to address the issue where your project exceeds the total supported prompt size.

​
Use knip.dev to remove unused files

Before proceeding, back up your project using both of these methods:

  • Click Export > Download to get a local copy of your project.
  • Click Export > Open in StackBlitz. With the project open in StackBlitz, click Fork. You’ll now see forked in the project title. Rename the project to something you can easily find if needed.

In the Bolt terminal run the following command:

npx knip --production --fix --allow-remove-files

Check the output in the terminal to see if the command ran successfully. This command removes unnecessary files from the codebase, which reduces the project size.

​
Use the .bolt/ignore file

If you open a Bolt project in StackBlitz you can edit a file called .bolt/ignore. In this file, you can list any files or folders that Bolt should exclude from the AI context window. For example, here is our Vite React starter’s ignore file.

There, you see the following files are ignored:

src/components/ui/*
hooks/use-toast.ts

These files are completely invisible to the AI, which frees up space in the context window. You’ll need to edit the .bolt/ignore file in StackBlitz and then reopen the project in Bolt for the changes to take effect.

Hiding files from the AI can have unintended consequences, as the AI is no longer aware of your entire project. This approach is powerful, but is only recommended for advanced users who can make informed decisions about what can safely be excluded, and can understand and resolve issues that may arise from this approach.

​
Split the project

Break a large app into smaller chunks, and glue it all back together outside of Bolt later. For example, separating the backend and frontend into different projects is a common developer pattern. Be careful doing this if you don’t have experience as a developer.

​
Bolt failed to deploy to Netlify

Manually deploy to Netlify:

  1. Run the project build command (usually npm run build).
  2. Click Download to download the project.
  3. Follow Netlify’s Manual deploy instructions.

​
Chat history or project disappears

To continue working on a project in a new browser:

  1. Log in to StackBlitz.com with your Bolt.new account.
  2. Open the Collections tab.
  3. Open the Bolt collection. You should see all of your projects there.
  4. Click the project, then use the Open in Bolt.new button to continue working on it in Bolt.

If your project is missing, this is a serious bug that requires Bolt’s help to investigate. Contact the support team at [email protected].

​
Out of memory (OOM)

This error occurs where there is no enough memory available to run the WebContainer environment. To free up system memory, close unnecessary applications and browsers tabs.

​
WebContainer startup error

Bolt relies on WebContainers, a browser based runtime from StackBlitz that enables a full stack development environment in the browser. If you encounter a WebContainer error, try the following:

  • Use Chrome or a Chromium based browser.
  • Selectively disable browser extensions, especially ad blockers, to see if this resolves the issue.
  • If accessing Bolt through a VPN, try again with the VPN disabled.

​
AI stuck or unresponsive

If the AI seems stuck or unresponsive to commands, resetting the AI context window can help. To do this, open your and fork your project in StackBlitz, followed by reopening the forked project in Bolt:

  1. With your project open in Bolt, click Export > Open in StackBlitz.
  2. In StackBlitz, click Fork. This creates a fork of your current project.
  3. Rename the forked project.
  4. Return to the StackBlitz dashboard by clicking the lighting bolt icon.
  5. Open your forked project.
  6. Click Open in bolt.new. You should now see your forked project open in Bolt without the previous chat history.