Documentation

Troubleshooting.

Eight things that go wrong with Roam, and the one command that usually fixes each one. Start with roam doctor — it diagnoses six of the eight.

Run roam doctor --json if you need to send us output.

1. Stale index after a pull, rename, or schema change

Symptom. Commands return symbols that don't exist anymore, miss new ones, or report a verdict that doesn't match the working tree. Often happens after git pull on a long-lived branch, after a large rename, or after upgrading Roam to a version that changed the SQLite schema.

Diagnose. roam doctor reports stale-index status; the schema-version check tells you if the DB is older than the installed roam-code version.

Fix. Rebuild from scratch. 

$ roam doctor
$ roam index --force

2. OneDrive / Dropbox / iCloud sync conflicts

Symptom. Random database is locked errors, partial writes, ghost conflict copies of .roam/index.db, or commands hanging on the first SQLite open. The cloud-sync client is racing the indexer for the file.

Diagnose. Check whether your project lives inside a synced folder. On macOS / Windows the path will contain iCloud Drive, OneDrive, or Dropbox.

Fix. Either move the project off the synced drive entirely, or exclude .roam/ from sync. On OneDrive: right-click the folder, "Always keep on this device" off, then add .roam/ to the unsync list. On Dropbox: dropbox exclude add .roam/. On iCloud: rename to .roam.nosync/ and update ROAM_DB_DIR, or move the repo out of ~/Documents.

3. Missing optional extras

Symptom. An ImportError on startup, or a "feature unavailable — install roam-code[X]" warning. Roam keeps the base install small and gates heavy dependencies behind extras.

Diagnose. roam doctor lists which extras are installed and which features are gated off.

Fix. Install the extra you need. 

# MCP server (FastMCP)
$ pip install "roam-code[mcp]"

# Semantic search (onnxruntime)
$ pip install "roam-code[semantic]"

# CLI file watcher (built-in polling)
$ roam watch  # no extra dependency required

# MCP reactive watcher (optional watchdog dependency)
$ pip install watchdog
$ ROAM_MCP_WATCH=1 roam mcp

4. Parser failures — zero symbols extracted from a file

Symptom. A file you know exists is missing from roam search results, or roam file <path> returns an empty skeleton. Usually a tree-sitter grammar load failure. On a fresh environment, first use may need tree-sitter-language-pack to populate its user cache. Roam pins a release that coordinates concurrent first-use loads and publishes cache files atomically. A persistent failure usually means acquisition is unavailable, the cache is not writable, or the install is incompatible. An unsupported extension is different: Roam skips that unavailable grammar (or uses a documented regex fallback) without attempting a download.

Diagnose. roam doctor reports the installed parser packages and parser-version drift recorded by the last index. Run roam index --force for an end-to-end grammar check.

Fix a supported grammar. Reinstall the exact Roam release so its tested grammar-pack range remains authoritative, confirm that the first-use download can reach its documented public destination and that the user cache is writable, then rebuild the index. Reinstalling cannot add an unsupported grammar; for that case, use a supported file type or add a language extractor before rebuilding. 

$ pip install --force-reinstall "roam-code==14.0.0"
$ roam doctor
$ roam index --force

5. Agent doesn't see Roam's MCP tools

Symptom. Claude Code, Cursor, Codex, or your own MCP-aware agent has Roam configured but doesn't list the Roam tools when you ask it. Usually the MCP server isn't starting, the binary isn't on the agent's PATH, or the editor's MCP config points at the wrong working directory.

Diagnose. Run the server directly. If it starts and lists tools, the problem is the editor's config. 

$ roam mcp --list-tools
$ which roam   # path the editor needs

Fix. See the per-editor walkthrough in /docs/integration-tutorials — it covers Claude Code, Cursor, Codex CLI, Gemini CLI, and Amp. The common gotcha: the editor MCP config must use the absolute path to roam, not the bare command, when running inside a sandboxed launcher.

6. Cache or DB permission errors

Symptom. PermissionError on .roam/index.db, .pytest_cache/, or ~/.cache/roam/. Usually because a previous run was launched as a different user (root via sudo, a CI runner UID, a Docker container) and left files the current user can't write.

Diagnose. ls -la .roam/ on Unix or icacls .roam on Windows shows the owner.

Fix. Reclaim ownership or wipe the cache. 

# macOS / Linux
$ sudo chown -R "$(whoami)" .roam .pytest_cache

# or wipe and re-init
$ rm -rf .roam && roam init

7. Out-of-memory during indexing on a large monorepo

Symptom. Indexer is OOM-killed on a repo with hundreds of thousands of files, or RAM climbs past available and the process slows to a crawl. Roam parses the working set in-memory before flushing to SQLite; very large monorepos can exceed reasonable RAM budgets.

Diagnose. roam doctor reports the file count and estimated parse-set size before you commit.

Fix. Exclude what you don't need to index — generated code, vendored dependencies, large fixtures — via a .roamignore file at the repo root (gitignore syntax). Then force a clean rebuild. 

$ echo 'vendor/' >> .roamignore
$ echo 'generated/' >> .roamignore
$ roam index --force

8. --json output is too verbose / too slow

Symptom. Piping roam <cmd> --json into an agent's context uses too many tokens, or the envelope wrapper makes line-oriented parsing awkward.

Diagnose. roam <cmd> --json | wc -c gives you the byte count. If the envelope is bigger than the payload, you want compact mode.

Fix. Use --compact for narrower envelopes (drops _meta, schema preamble, and optional fields). 

$ roam impact AuthService --json --compact
$ roam preflight AuthService --json --compact

Still stuck?

Email [email protected] with the output of roam doctor --json attached. That dump tells us your roam-code version, Python version, installed extras, schema version, language coverage, and index health — usually enough to identify the issue without a back-and-forth. 

$ roam doctor --json > roam-doctor.json

For bug reports, file an issue at github.com/Cranot/roam-code with the same dump attached.

See it run: The 5-minute canonical demo — install → health → preflight → critique → signed ChangeEvidence packet, end to end. If you can run this on a clean venv, your install is healthy.

Related docs: Getting Started for the first-run path, Using Roam via MCP for agent / editor setup, Command Reference for the full CLI surface.