Skip to content

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

    # 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, grammar load status, and the supported extension map.

Fix. Reinstall with the latest grammar pack.

    $ pip install --upgrade tree-sitter-language-pack
    $ 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 hello@roam-code.com 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.