Bolt issues

​

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.

​

Bolt didn’t do everything you asked in your prompt

When using LLMs, break big changes into smaller pieces. Focus on one area or feature at a time, instead of trying to do many things at once.

1. Make a change.
2. Check if the change works.
3. Move on to the next change.

For each change, provide a specific request. Be clear about what part of the app you’re working on, don’t assume Bolt remembers previous parts of the conversation, and try to show Bolt what you want.

Prompt effectively contains more detailed guidance to writing effective prompts.

​

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 to remove unused files

Knip is a tool to automatically declutter projects.

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

• Click Export > Download to get a local copy of your project.
• Open the menu next to the project name, then click Duplicate to create a fresh copy of your project in Bolt.

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.

Open the project in StackBlitz:

1. Log in to your StackBlitz account.
2. Go to Collections > Bolt collection.
3. Click the project you want to open.

Edit the .bolt/ignore file:

1. In the FILES menu, open the .bolt directory.
2. Either:
   • Click ignore to open the file in the editor.
   • If there isn’t an ignore file, right-click the .bolt directory, then click New File. Name the file ignore.

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.

​

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.

​

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 duplicate your project, then work in the new copy of the project. If you want to keep some information from the chat, create a summary of the old chat.

Get the AI to summarize your chat history:

1. Switch to Discussion Mode: in the Bolt prompt box in your project, click Toggle
2. Prompt the AI: Please generate a short summary of our conversation so far.
3. Check that the AI response is accurate and contains everything you need.
4. Copy the response out of Bolt and save it as a .txt or .md file.

Then, reset the context window:

1. Open the menu next to the project name.
2. Click Duplicate.
3. If you have integrations active in the project, Bolt displays a dialog that confirms which integration settings it will copy. Click Duplicate in the dialog to continue.
4. Bolt creates a new copy of the project, with an empty chat history.

In your new project, add the chat summary:

1. Switch to Discussion Mode: in the Bolt prompt box in your project, click Toggle
2. Click Upload files
3. Provide a prompt such as:

   The attached file is a summary of previous discussion about this project.
   Please use it when working on future changes.

4. Press Enter to upload the file and your prompt.

​

Chat history or project disappears

To continue working on a project in a new browser:

1. Log in to StackBlitz.com with your Bolt 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 | AI 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 isn’t 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.