Bolt issues

​

Tips to avoid issues

Before trying other troubleshooting steps for Bolt, start with these checks:

• Make sure you’re using Chrome or another Chromium-based browser.
• Temporarily disable browser extensions, especially ad blockers, to see if the issue clears.
• If you’re using a VPN, turn it off and try again.
• Check whether your antivirus software is blocking Bolt assets, particularly if you see a 403 or 404 error.

​

White screen, grey screen, or no preview showing

If you see a white or gray screen with nothing in the preview window, follow these steps in order.

1. Refresh your project in the browser.
2. If that doesn’t fix the issue, try prompting Bolt with: The preview is not showing, fix this. This will resolve the issue in some but not all cases. If this doesn’t resolve the issue, repeated prompting likely won’t be successful and will simply use up tokens.
3. Depending on which agent you’re using, switch to either Discussion Mode or Plan Mode to help you troubleshoot. Then use the following prompt: The preview is not showing. Troubleshoot potential issues and suggest steps to resolve. Review Bolt’s response and decide on a course of action.

​

Use npm run build

If the steps above don’t fix the problem, you can try one last option: running the npm run build command in the terminal. This can help rebuild your project and resolve underlying issues. To do so, follow these steps:

1. Click the code icon to switch to Code View.
2. Click Terminal in the bottom section of the page.
3. Type npm run build, then press Enter.
4. Click the eye icon to return to Preview Mode to confirm if your issue is resolved.

​

Bolt didn’t do everything you asked in your prompt

When working with LLM-based tools like Bolt, it’s best to approach big updates in small, manageable steps. Large or complex requests can easily overwhelm the system or lead to unclear results or errors. Focus on one feature or section at a time rather than trying to handle multiple changes at once. This approach makes it easier to track progress, identify issues, and maintain control over your project. Follow this simple process:

1. Make one change.
2. Check that the change works as expected.
3. Then move on to the next change.

For each update, give a clear and specific request. Mention which part of the app you’re working on, and don’t assume Bolt remembers earlier parts of the conversation. When possible, show examples or describe exactly what you want to achieve. For more detailed tips on writing effective prompts, see Prompt effectively.

​

Prompt too long, or project exceeds total supported prompt size

You can use the following methods to reduce your project’s size if it exceeds the supported prompt limit:

​

Clean up unused files

Bolt uses a tool called Knip to perform a cleanup. You can run this when prompted by Bolt, or run it manually at any time. Before proceeding, back up your project using one or both of these methods:

• In the top left of your screen, click the project title, then click Export > Download, or
• In the top left of your screen, click the project title, then click Duplicate.

Automatic cleanup when prompted If your Bolt project exceeds the context window, you’ll see a message in chat: Project size exceeded. The context window is the maximum amount of information Bolt can process at once. Paid plans offer larger windows, allowing bigger projects before reaching this limit. Click Remove unused files to run the cleanup. Manually run the cleanup 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.

Open the Bolt terminal

1. Log in to your project.
2. Click the code icon (<>) in the top center of your screen to switch to Code view.
3. Scroll down to the bottom, then click Terminal.

​

Use the .bolt/ignore file

In the .bolt/ignore file, list any files or folders that Bolt should exclude from the AI context window.

1. Log in to your Bolt project.
2. Click the code icon (<>) in the top center of your screen to switch to Code view.
3. Either:
   • In the .bolt directory, 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.
4. List the files you want Bolt to ignore. Provide the full path to the files, including directories. You can use * as a wildcard. For example: to ignore all files in a directory called test, write test/* in your ignore file. These files are now completely invisible to the AI, which frees up space in the context window.

​

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.

​

Advanced techniques

You can also use terminal commands to help reduce your project size. These commands are especially useful once you’ve completed the earlier cleanup steps and want to make sure no unnecessary code or dependencies remain. Find and remove unused dependencies

1. Click the code icon to switch to Code View.
2. Click Terminal in the bottom section of the page.
3. In the terminal, run npx depcheck to scan your project for any dependencies that are not being used in your codebase.
4. Review the results and remove any unused packages listed in the output. This keeps your project lightweight and easier to maintain.

Check and clean up package versions

1. Click the code icon to switch to Code View.
2. Click Terminal in the bottom section of the page.
3. Run npm dedupe to analyze your installed packages and remove duplicate or outdated versions of dependencies.

​

Bolt stuck or unresponsive

If Bolt becomes stuck or stops responding to commands, clearing the context can often resolve the issue. You can clear the context in Bolt by entering the /clear command in your chatbox, then clicking Clear context in the Results section above.

​

Project disappears

If you’re logged into the Bolt homepage and don’t see your project in the menu that appears when you hover over the left side of the screen, you can try recovering it through your StackBlitz account. Follow these steps:

1. Sign in to your StackBlitz account.
2. In the left-hand menu, click Collections.
3. Click the Bolt collection.
4. Locate your project and click its title to open it.
5. In the top-left corner of the screen, click Open in bolt.new to reopen it in Bolt.

If your project still doesn’t appear, it may indicate a serious issue that needs investigation. Contact [email protected] for help.

​

Site can’t provide a secure connection

If you see an error like this when publishing your site: This site can’t provide a secure connection.
<your-site>.bolt.host sent an invalid response.
ERR_SSL_PROTOCOL_ERROR the issue is usually related to your WiFi or router settings. Every internet provider and router setup is a little different, but most include an option to manage trusted domains. Open your WiFi or router settings, look for that area, and add .bolt.host to your list of allowed or trusted domains. If you still see the error after making that change, try connecting to a different WiFi network or use your phone’s hotspot. If your site publishes successfully, you will have confirmed the problem is with your original network settings rather than with Bolt.

​

Out of memory (OOM)

This error appears when your system doesn’t have enough available memory to run the WebContainer environment, which powers projects in Bolt and StackBlitz. The WebContainer relies on your local device’s resources to simulate a full development environment inside the browser, so limited memory can cause it to fail to start or crash unexpectedly. To resolve this:

1. Close unnecessary browser tabs and background applications to free up system memory.
2. If you’re running multiple Bolt or StackBlitz projects at once, close all but the one you’re actively working on.
3. Refresh your browser and try reopening the project.
4. If the problem persists, restart your device to clear cached processes and release additional memory.

If you regularly encounter this error, consider using a browser with fewer extensions or increasing available system memory.

​

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:

• Make sure you’re using Chrome or another Chromium-based browser.
• Temporarily disable browser extensions, especially ad blockers, to see if the issue clears.
• If you’re using a VPN, turn it off and try again.