Troubleshooting

Search results look stale

Indexed results state their freshness. Reindex changed files, or re-run the derived phases without a full re-parse:

bb index --changed
# or, when only derived data (relationships, health) is stale:
bb index --post

Repair a corrupted index

Wipes this project's index and rebuilds it in place. Your source files are never touched:

bb index --force

An index run was interrupted

Check where the run stopped, then continue from its checkpoint:

bb status
bb index --resume

Semantic search is weak or unavailable

Without a configured embedding provider, semantic modes fall back to weaker local vectors. Check your setup and its consistency:

bb setup show
bb doctor

Configure a provider with bb setup. bb doctor --fix repairs file-permission problems only (0600 on the config) — it is explicit and changes nothing else.

A tool reports missing or fresh=false data

Tool results carry a freshness block (fresh/stale/missing counts plus a remediation command). Run the remediation it names — usually bb index --changed or bb index --post:

bb health

Verbose diagnostics

Show debug logs and per-file worker/WASM lines for any command; suppress informational output with --quiet:

bb --verbose stats
bb --quiet search createSession