Troubleshooting

Common issues and solutions.

Installation

“Command not found: cerebro”

Make sure the cargo bin is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Add this to your shell profile, such as ~/.zshrc or ~/.bashrc, to persist.

“Couldn’t find cerebro”

Run cargo install cerebro from the project directory:

cargo install --path .

Configuration

“Config file not found”

Create config.toml:

cp config.toml.example config.toml

Or create manually:

[settings]
opencode_db_path = "~/.local/share/opencode/opencode.db"
pi_sessions_path = "~/.pi/agent/sessions"
output_dir = "./content"

[[projects]]
name = "my-project"
repo_path = "~/Projects/my-project"
active = true

“Couldn’t parse config”

Check your TOML syntax:

• Use = not :
• String values need quotes: "path" not path
• Arrays use brackets: [[projects]] not [projects]

Validate with:

cargo run -- build

“Repo not found”

Verify repo_path exists:

ls -la ~/Projects/my-project

Build

“No activity found”

Likely causes:

• No git commits yet: Commit something first
• No AI sessions: Only relevant if you have configured opencode_db_path or pi_sessions_path
• No TODOs: Add a TODO or Needs Fixing comment

This is normal for new projects. Activity appears as you work.

“Build is slow”

First build can be slow on large repos. Subsequent builds use cache.

Force a fresh build:

cerebro build --fresh

Clear cache manually:

cerebro status
# Note the cache location
rm {cache_file}

“OpenCode database not found”

Set the correct path in config:

opencode_db_path = "~/.local/share/opencode/opencode.db"

Verify the file exists:

ls -la ~/.local/share/opencode/opencode.db

MCP server

“MCP tools not available”

Restart OpenCode after configuring the MCP server.

Set CORTEX_PATH if your cortex data dir is not at the default ~/Projects/cortex:

export CORTEX_PATH="~/Projects/my-data-dir"

Test the server directly:

cargo run -p cerebro-mcp

“No projects found in MCP”

Verify your config includes the project and it’s set to active = true.

Serving

“Port already in use”

Pick a different port:

cerebro serve --port 3001

“Dashboard not updating”

Rebuild with --fresh:

cerebro build --fresh

Then refresh your browser.

General

“Unexpected behavior”

Run with debug logging:

RUST_LOG=debug cargo run -- build

“It’s broken and the cause is unclear”

Clear everything and start fresh:

# Remove output
rm -rf ~/cerebro-dashboard

# Remove cache
rm -rf ~/Library/Caches/cerebro  # macOS
rm -rf ~/.cache/cerebro          # Linux

# Rebuild
cerebro build --fresh