Skip to content

FAQ & Troubleshooting

Jump to bottom
Stanley edited this page Aug 28, 2026 · 2 revisions

FAQ & Troubleshooting

Small answers that don't warrant a tracked docs/ page. For authoritative references see docs/.

Install / first run

cairn update reindexes 0 files on a fresh clone

That's expected — cairn update diffs against git HEAD, which is empty on a clean checkout. Use cairn build for the first run, then cairn update for day-to-day edits.

cairn build      # first run: parse everything
cairn update     # later: only changed files

cairn install-agents --client claude,cursor fails

Click's multiple=True doesn't accept comma-separated values. Repeat the flag:

cairn install-agents --client claude --client cursor

I installed for opencode but can't uninstall it

Fixed in 0.6.1 — opencode is now in both uninstall choice lists. On older versions, run cairn uninstall-agents without --client (it removes all detected clients).

Where does the graph live?

Under ~/.cairn/<workspace-key>/ by default. Override with CAIRN_HOME, CAIRN_DB (graph), or CAIRN_KNOWLEDGE (the markdown bundle). With a custom CAIRN_HOME, generated agent registrations carry it automatically (re-run cairn install-agents after moving the store). See configuration.md.

Can I move the .kg database between machines?

Yes — paths are stored repo-relative (portable) since 0.5.0. Copy the .kg into the recipient's ~/.cairn/<key>/ store or point CAIRN_DB at it. Paths are reconstructed to absolute only at disk-I/O time via scanner.resolve_file_path.

Languages / parsing

C / C++ files produce "No parser for c" errors

The scanner recognizes .c/.cpp/.cc/.cxx/.hpp/.h extensions (and .h is sniffed to objc/cpp/c), but no tree-sitter parser ships for C/C++ yet. The files are scanned and hash-statted but recorded as parse_errors.

Interim: configure a pre-built SCIP index (e.g. from clang-based indexers) in cairn.json under scip.

Rust files aren't picked up at all

Rust isn't in EXTENSION_MAP today (asymmetric with C/C++). Route via rust-analyzer scip and declare the index under scip → rust.

Route / service-call detection doesn't fire for my backend

  • Route detection is TypeScript/JavaScript-only (NestJS / React Router / Next.js).
  • Service-call detection covers TS/JS/Go/Kotlin/Java (fetch / axios / http.Get / OkHttp / Retrofit idioms).

Python (FastAPI), Swift (URLSession), Dart, etc. are gaps. The edge taxonomy is documented in architecture.md.

MCP / agents

The MCP client connects but the graph looks empty (custom CAIRN_HOME)

This is the #70 failure class: cairn resolves its store from the process environment, so a client-spawned server that doesn't inherit CAIRN_HOME silently resolves an empty default store instead of yours. As of the env-propagation change (post-0.16.0), cairn install-agents embeds env.CAIRN_HOME into every generated stdio registration (and hooks / the LaunchAgent plist carry it too), and a missing store fails with the resolved path + env chain instead of a raw sqlite error.

Fix on an older install: re-run cairn install-agents with CAIRN_HOME set, then diagnose anything still miswired with:

cairn config --json   # what THIS environment resolves (4 paths, JSON)
cairn doctor          # the `environment` check names client/store mismatches,
                      # dead SSE endpoints, and platform limitations

On Linux with an SSE registration, expect a WARN: cairn serve start is macOS-only (launchd) — use stdio or run cairn serve --port 9876 under a process supervisor.

How many MCP tools are there?

27, across 4 layers: graph (9), compass + knowledge base (5), memory (8), knowledge (5). The server asserts this count at boot (server.py:_EXPECTED_TOOL_COUNT = 27); mismatch fails fast.

An MCP tool rejects a parameter the docs mention

Check whether the doc is describing the library layer vs the MCP surface. For example, kind= filtering on get_callers/get_callees exists in cairn.graph.traversal and via the CLI, but the MCP wrappers don't expose it. Open an issue if the gap surprises you.

explore returns semantic hits even with CAIRN_FUSION=0

CAIRN_FUSION=0 only disables the RRF blend inside semantic_search. explore still runs semantic seed expansion when FTS returns fewer than 3 seeds, regardless of fusion. This is by design (sparse-query recall).

Fresh AGENTS.md / CLAUDE.md looks wrong after install

Fixed in 0.6.1 — the install template (_INSTRUCTIONS_BODY) was stale on three claims (ANN backend default, recall_memory behavior, layer breakdown). On older versions, the committed AGENTS.md in the repo is the source of truth; re-apply it manually or upgrade.

Performance

Embeddings are slow / torch is huge

The default install is torch-free. semantic_search and reranking need the [semantic] extra (one-time ~836 MB model download):

pip install cairn-intel[semantic]
cairn embed --install-deps
cairn embed

For large corpora, add [ann] (sqlite-vec, on by default if installed) — see configuration.md.

cairn build is slow on a huge repo

Tune CAIRN_WORKERS (default = CPU count), and use cairn.json exclude / include to drop vendored / generated dirs from the graph.

Still stuck?

  • Search open issues.
  • Check the CHANGELOG — your issue may already be fixed in an unreleased version.
  • Open a new issue with the cairn version output and the exact command + error.

Clone this wiki locally