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 --rebuild

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]"

# File watcher (watchdog)
$ pip install "roam-code[watch]"

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: the tree-sitter-language-pack version installed in your environment is older than what Roam expects, or the file extension isn't mapped to a grammar.

Diagnose. roam doctor lists language coverage and grammar load status; roam languages shows the supported extension map.

Fix. Reinstall with the latest grammar pack. 

$ pip install --upgrade tree-sitter-language-pack
$ roam doctor
$ roam index --rebuild

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 --exclude patterns or .roamignore. 

$ roam index --exclude 'vendor/**' --exclude 'generated/**'
$ echo 'vendor/' >> .roamignore
$ roam index --rebuild

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.