Troubleshoot common Bolt issues

Most Bolt problems fall into a small number of categories. Work through the relevant accordion below, and check the log output with bolt logs whenever something unexpected happens.

For questions that aren’t answered here, search or start a discussion in the Bolt GitHub Discussions. Include the output of bolt debug info and bolt logs --tail 50 in your post so the community can help faster.

First things to try

Before diving into a specific section, these four commands solve most problems:

Symptom	First command	Why
Anything weird	`bolt debug info`	One-shot system + plugin summary.
Something worked before, now it doesn’t	`bolt logs --tail 100`	Recent errors, usually near the top.
Suspect a plugin	`bolt --pure`	Start with all plugins disabled.
Config isn’t being picked up	`bolt debug config`	Prints the fully-resolved config.

The bolt debug family is your first stop for any mysterious behavior. bolt debug info for a system summary, bolt debug config for the resolved config, bolt debug paths for on-disk locations, and bolt debug snapshot to inspect session state.

Bolt doesn't start / crashes on launch

Symptoms: The terminal flashes and exits immediately, or you see a stack trace before the TUI renders.Steps:

Collect system information

bolt debug info

This prints your Bolt version, OS, terminal emulator, and loaded plugins. Copy this output when reporting a bug.

Check recent log output

bolt logs --tail 100

Look for ERROR lines. A common cause is a plugin that fails to load — in that case you’ll see an error mentioning the plugin name.

Disable plugins to isolate the issue

bolt --pure

If Bolt starts cleanly with --pure, a plugin is causing the crash. Remove the offending plugin from your config, or report it to the plugin author.

Check for corrupted config

bolt debug config

If this prints an error about invalid JSON, open the config file it mentions and fix the syntax. Run bolt db path to confirm the database path is accessible.

Provider authentication fails

Symptoms: Bolt shows “No providers configured”, API requests fail with 401 errors, or bolt run exits immediately without producing any output.Steps:

Re-run the provider login flow

bolt providers login

Select your provider and follow the prompts. Bolt will walk you through API key entry or OAuth.

Verify the API key environment variable

If you use an env var (e.g. ANTHROPIC_API_KEY), confirm it is actually set in the current shell:

echo $ANTHROPIC_API_KEY

If it is empty, add it to your shell profile and re-open your terminal.

Inspect the resolved config

bolt debug config

Look at the provider section. If your provider appears with a blank apiKey, the environment variable reference in your config file is not being expanded.

List stored credentials

bolt providers list

This shows all credentials stored in auth.json and all provider-related environment variables that Bolt detected.

MCP server won't connect

Symptoms: bolt mcp list shows a server as failed or needs authentication, or the agent cannot use any tools from that server.Steps:

Run the MCP debug probe

bolt mcp debug <server-name>

This tests basic HTTP connectivity, inspects the WWW-Authenticate header, and walks through the OAuth discovery flow if applicable. The output will tell you whether the server is reachable and whether auth is required.

Check the server URL

Verify the URL in your .bolt/bolt.jsonc. For remote servers, make sure the URL ends with the MCP path (e.g. /mcp or /tools), not just the host.

Re-authenticate for OAuth servers

bolt mcp auth <server-name>

Follow the browser flow. If the server requires a pre-registered client ID, add it to the config:

"mcp": {
  "my-server": {
    "type": "remote",
    "url": "https://mcp.example.com/tools",
    "oauth": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    }
  }
}

Check local server command

For local servers, run the command manually in your terminal to confirm it starts without errors:

npx @modelcontextprotocol/server-filesystem /tmp

Session not found

Symptoms: bolt run --session <id> exits with “Session not found”, or a session you remember working with has disappeared.Steps:

List all available sessions

bolt session list

Sessions are sorted by most-recently-updated first. If your session was deleted or the database was migrated, it will not appear here.

Find the database path

bolt db path

This prints the full path to the SQLite file. Verify the file exists and is not empty.

Query the database directly

bolt db "SELECT id, title FROM sessions ORDER BY time_updated DESC LIMIT 20"

If your session appears in the database but not in bolt session list, there may be a project ID mismatch — sessions are scoped to projects.

Permission errors in the TUI

Symptoms: The agent asks for permission repeatedly, refuses to write files, or you see “Permission denied” banners.Understanding access levels:Each built-in agent has a declared access level that controls what it can do without asking:

Access level	What it allows
Full	Read files, write files, run shell commands
Edit	Read and write files, no shell commands
Read	Read files only, no writes or commands

The code, debug, refactor, migrate, and perf agents have Full access. docs has Edit access. plan, ask, code-review, and security have Read access.Steps:

Switch to an agent with Full access

If you need file writes, use the code agent:

bolt run --agent code "implement the feature"

Or press Tab in the TUI to cycle through agents.

Use --auto to approve prompts non-interactively

In CI or scripted contexts, pass --auto to bolt run to auto-approve permissions that are not explicitly denied in the config.

Configure permissions in the config file

You can deny specific tools for all sessions in a project by adding a permission block to .bolt/bolt.jsonc.

High token usage or unexpected costs

Symptoms: bolt stats shows higher token counts than expected, or your API bill is growing faster than anticipated.Steps:

Review your usage statistics

bolt stats
bolt stats --days 7 --models

The output breaks down cost per day, average tokens per session, and usage by model.

Lower the reasoning effort

For models that support it, reduce the reasoning effort with --variant:

bolt run --model anthropic/claude-opus-4-5 --variant minimal "quick review"

Supported values are provider-specific (e.g. minimal, low, high, max).

Switch to a cheaper model

Use bolt models to find a smaller model. Smaller models (e.g. claude-haiku, gpt-4o-mini) cost significantly less per token and work well for many tasks.

Use the ask or plan agent for exploration

The ask and plan agents have Read access and do not invoke write tools, which means they avoid tool-heavy loops that generate large output tokens.

Plugin conflicts or unexpected behavior

Symptoms: A slash-command behaves unexpectedly, the TUI renders incorrectly, or something changed after installing a plugin.Steps:

Disable all plugins to establish a baseline

bolt --pure

If the issue disappears, a plugin is responsible.

Identify the offending plugin

bolt debug info

The output lists all loaded plugins. Temporarily remove them one at a time from your config and restart Bolt until the issue is gone.

Check for version incompatibility

bolt upgrade

Plugins declare a compatible Bolt version range. If you recently upgraded Bolt, a plugin may need to be updated as well.

WSL / Windows path issues

Symptoms: On Windows with WSL, Bolt cannot find less, file paths contain unexpected backslashes, or the pager for bolt session list does not launch.Steps:

Set the Git Bash path

Bolt looks for Unix utilities (including less) relative to the Git for Windows installation. Set the environment variable to your Git Bash directory:

$env:BOLT_GIT_BASH_PATH = "C:\Program Files\Git\bin"

Add this to your PowerShell profile ($PROFILE) to persist it.

Verify with debug info

bolt debug info

Confirms the OS detection and which paths Bolt is using.

Run Bolt inside WSL directly

For the best experience on Windows, run bolt from within a WSL terminal rather than from PowerShell or Command Prompt.

Can't upgrade Bolt

Symptoms: bolt upgrade reports an error or silently does nothing, or the version number does not change after running it.Steps:

Specify the installation method explicitly

Bolt tries to detect how it was installed. If detection fails, override it:

bolt upgrade --method npm
bolt upgrade --method curl
bolt upgrade --method brew

Reinstall via the install script

curl -fsSL https://raw.githubusercontent.com/bolt-builder/bolt-cli/dev/install | bash

Windows: run as Administrator for Chocolatey

If you installed via choco, upgrades require an elevated terminal. Open PowerShell as Administrator before running bolt upgrade.

Confirm the new version is active

bolt --version
which bolt    # verify the PATH is picking up the right binary

Agent can't find files (or finds too many)

Symptoms: The agent complains it can’t see files that exist, or repeatedly picks up files you don’t want it to touch (like node_modules, build output, or secrets).Steps:

Check for a .boltignore

Bolt honors a .boltignore file at the project root that controls which files the agent’s file-search tools can see. It uses the same syntax as .gitignore.

# .boltignore
node_modules/
.env*
dist/
*.pem

Confirm the working directory

bolt debug info

Verify the cwd matches the project root. If you launched Bolt from a subdirectory, the agent’s file search is rooted there.

Ask the agent to grep, not guess

If the agent claims a file doesn’t exist, ask it to run grep or glob explicitly. This bypasses any stale internal assumption.

Getting debug info for a bug report

When filing an issue, the following information is most useful to maintainers:

Collect system and plugin info

bolt debug info

Collect recent log output

bolt logs --tail 200

Export the relevant session (sanitized)

If the problem happened during a specific session, export it with secrets redacted:

bolt export --sanitize > session-debug.json

Attach session-debug.json to the issue.

Open an issue or discussion

Go to GitHub Discussions and paste your bolt debug info output plus a description of the steps to reproduce.

Get Started

Core Concepts

TUI

Extending Bolt

Server & Automation

Desktop App

Reference

Troubleshoot common Bolt issues

First things to try

​First things to try

First things to try