This troubleshooting guide is designed to assist users encountering issues while using Bolt. If your specific issue is not listed here, please contact [email protected], and we’ll ensure it gets added to the guide.

Before you jump down into the section that corresponds with the issue you are facing, please ensure that:

  • You are using Chrome or a Chromium based browser as Bolt.new is the most compatible with these environments
  • Selectively disable browser extensions, especially ad blockers, to see if this resolves the issue
  • If accessing bolt.new through a VPN, try again with the VPN disabled

If you have confirmed that your issue is not resolved by the above, jump into the section that reflects the issue you are facing.

​
White Screen/Grey Screen/No Preview showing

If the above does not resolve the issue, try the following:

Prompt Bolt: “The preview is not showing, please fix this”. This may resolve the issue in some but not all cases. NOTE: If this does not resolve the issue, repeated prompting will not be successful and you should move on to the following methods to preserve tokens.

​
Prompt Too Long/Project Exceeds Total Supported Prompt Size

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

1

Use knip.dev to remove unused files:

Before proceeding, make sure to backup your project by both of these methods:

  • Clicking Export > Download at the top-right in Bolt to download a local copy of your project.
  • Clicking Export > Open in StackBlitz. With the project open in StackBlitz, click Fork at the top-left of the page. You will now see “forked” in the project title. Rename the project to something you can readily find if needed.

With these backups created, in the Bolt terminal enter and run the following command:

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

This will remove unnecessary files from the code base which should reduce the project size.

2

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 should be excluded from the AI context window. For example, here is our Vite React starter’s ignore files: https://stackblitz.com/edit/vite-shadcn?file=.bolt%2Fignore.

There, you see the following files are ignored:

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

These files will be completely invisible to the AI which will clear 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 it 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/resolve issues that may arise from this approach.

​
Additional Troubleshooting

If you have received an error message that is not described above, you can try two things:

  1. Copy and past the error message itself directly into Bolt and ask it to resolve the problem.
  2. Research the error message using another LLM (such as ChatGPT) and paste the described solutions back into Bolt.

If neither of these methods, then Bolt will not be able to resolve your issue as it stands. In this case, you will need to research the problem, such as by consulting official documentation, and apply a fix manually.

HostingWebContainer Startup Error