How to troubleshoot

How-to: troubleshoot

Real errors from real runs (2026-08-31), with the fix that worked.

Symptom	Cause	Fix
claude mcp list shows ⏸ Pending approval	project-scope .mcp.json servers need a one-time in-app approval (Claude Code security)	run claude once and approve — or use the claude mcp add one-liner (local scope, connects immediately)
Server "defined in multiple scopes" warning	cie init (project scope) + the one-liner (local scope) both registered	keep one: claude mcp remove cie -s project (or -s local)
Client can't spawn the server (GUI-launched app)	bare cie-mcp not on the client's PATH	cie init writes spawn-robust absolute entries; or register with $(command -v cie-mcp)
no embedded graph database at …	you queried before indexing (or from the wrong dir)	cie index . first; check --db/CIE_DB
Server started but queries hit the wrong store	backend auto picked the other backend	read the stderr line (backend=… storage=…); pin with --backend or CIE_BACKEND
CIE_BACKEND=garbage didn't error	by design — stray values fall through to auto, never fatal	set a valid value or unset it
test_map returns 0 for a tested symbol	TESTS edges are heuristics; a test that only reaches the target via a helper isn't linked (v0.1.4 added direct-calls: 1 → 562 on cie itself)	name tests after behavior and call the target directly, or accept the honest miss (the hint says exactly this)
sync tools: "the two-graph model requires a non-empty project"	Neo4j-mode sync tools are project-scoped	pass --project <name>
Optional-dep envelope unavailable[OPTIONAL_BACKEND_MISSING:...]	you didn't install the extra	pip install "cie-mcp[mcp]" / …[http] — or it's env-gated by design (embeddings need explicit CIE_EMBED_DSN + key)
Empty results that look wrong	check the envelope's hint — empty answers explain themselves	fix the input the hint names (e.g. affected_by wants a file path, not a symbol)