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 (~/.zshrc or ~/.bashrc) to persist.

“could not 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]
cache_ttl_hours = 24
opencode_db_path = "~/.local/share/opencode/opencode.db"
output_dir = "./content"

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

“could not 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 OpenCode sessions — Use OpenCode in that project
• No TODOs — Add a TODO or FIXME 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.

Ensure CORTEX_PATH is set to your 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 I don’t know why”

Clear everything and start fresh:

# Remove output
rm -rf ~/cerebro-dashboard

# Remove cache  
rm -rf ~/Library/Caches/cerebro

# Rebuild
cerebro build --fresh