Skip to content
Trurlic

Troubleshooting

graph.toml is missing or corrupt

Section titled “graph.toml is missing or corrupt”

Symptom: trurlic serve or trurlic status errors with “graph.toml not found” or a parse error.

Fix: Rebuild the index from node files:

Terminal window
trurlic check --rebuild

This regenerates graph.toml deterministically from the TOML files in components/, decisions/, and patterns/. Non-inferable edges (ConnectsTo, DependsOn, Constrains, Supersedes) can’t be reconstructed from node files — re-add them afterward.

BLAKE3 hash mismatch

Section titled “BLAKE3 hash mismatch”

Symptom: trurlic check warns about a hash mismatch.

Cause: A node file was changed outside Trurlic (hand edit, git merge, external tool).

Fix: Run trurlic check to reconcile — an intentional edit updates the hash. If the change was unintended, inspect the file and revert.

File lock contention

Section titled “File lock contention”

Symptom: CLI commands hang while the MCP server is running.

Cause: A write tool is holding the file lock — normally released in milliseconds.

Fix: If it persists, a trurlic serve process may be stuck. Check for zombie processes and restart the server.

MCP server not connecting

Section titled “MCP server not connecting”

Symptom: Your IDE agent can’t find or reach the Trurlic MCP server.

Checklist:

  1. Is the config correct? Run trurlic install --ide <target> --dry-run and compare with your IDE’s MCP config.
  2. Is the working directory right? serve reads .trurlic/ from the launch directory — the IDE must start it in your project root.
  3. Is trurlic on PATH? Run which trurlic. If installed via cargo install, ensure ~/.cargo/bin is on PATH — or pass an absolute path with install --binary-path.

Quick fix: re-run trurlic install --ide <target>. See Connect Your IDE.

Component not found

Section titled “Component not found”

Symptom: advance or get_context returns “component not found.”

Fix: Check the spelling — names are kebab-case. List components with trurlic status. Use project (not a real component) for project-wide rules.

Decision write rejected

Section titled “Decision write rejected”

Symptom: record_decision (or trurlic decide) returns a validation error.

Common causes:

  • Component doesn’t exist — add it first (add_component / trurlic add component).
  • Dangling edge — depends_on or constrains names a decision that doesn’t exist.
  • Cycle — the proposed DependsOn edge would create one.
  • Reserved name — project and all can’t be component names.

Every mutation validates the full graph first, so an invalid write is refused whole — nothing partial lands on disk.

Map won’t open

Section titled “Map won’t open”

Symptom: trurlic map starts the server but no browser appears.

Fix: On headless or WSL environments opener may fail silently. The URL is always printed to stdout — start with --no-open and open it manually:

Terminal window
trurlic map --no-open

Bootstrap recorded little or nothing

Section titled “Bootstrap recorded little or nothing”

Symptom: After a bootstrap run, few decisions were recorded.

Cause: The agent may lack file read access, or the project is small.

Fix: Verify the agent can read your source. For small projects, an interactive design conversation often captures more than autonomous extraction.

Getting help

Section titled “Getting help”