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 parse errors.

Solution: Rebuild the index from node files:

Terminal window
trurlic check --rebuild

This regenerates graph.toml deterministically from the TOML node files in components/, decisions/, and patterns/. Note: non-inferable edges (ConnectsTo, DependsOn, Constrains) cannot be reconstructed from node files alone — they will be lost. Re-add connections after rebuild.

BLAKE3 hash mismatch

Section titled “BLAKE3 hash mismatch”

Symptom: trurlic check warns about hash mismatches.

Cause: A node file was modified outside Trurlic (hand edit, git merge, external tool) without updating the graph index.

Solution: Run trurlic check to reconcile. If the edit was intentional, the check will update the hashes. If the edit was unintentional, inspect the file and revert if needed.

File lock contention

Section titled “File lock contention”

Symptom: CLI commands hang or return slowly when the MCP server is running.

Cause: A write tool is holding the file lock. This should resolve in milliseconds — write tools complete in under 50ms.

Solution: If the hang persists, the MCP server may be stuck. Restart it. Check for zombie trurlic serve processes.

MCP server not connecting

Section titled “MCP server not connecting”

Symptom: IDE agent cannot find or connect to the Trurlic MCP server.

Checklist:

  1. Is the server running? trurlic serve must be started before the agent connects.
  2. Is the config correct? Run trurlic install --ide <target> --dry-run to see the expected config snippet, and compare with your IDE’s MCP configuration file.
  3. Is the working directory correct? trurlic serve reads .trurlic/ from the current directory. The IDE must launch the server from your project root.
  4. Is trurlic on PATH? Run which trurlic to verify. If installed via cargo install, check that ~/.cargo/bin is in your PATH.

Quick fix: Use trurlic install --ide <target> to auto-write the correct MCP configuration for your IDE. See CLI Reference — trurlic install for supported targets.

Design conversation fails to start

Section titled “Design conversation fails to start”

Symptom: trurlic design exits with an API key error.

Checklist:

  1. Is an API key set? Check echo $ANTHROPIC_API_KEY (or the relevant provider’s variable).
  2. Is the config file readable? Check ls -la ~/.config/trurlic/config.toml — permissions must be 600 (owner-only).
  3. Are multiple keys set without a provider flag? If both ANTHROPIC_API_KEY and OPENAI_API_KEY are set, Trurlic requires -p to disambiguate. Alternatively, set default_provider in the config file.

Ollama connection refused

Section titled “Ollama connection refused”

Symptom: trurlic design -p ollama fails with a connection error.

Cause: Ollama is not running, or it’s on a non-default address.

Checklist:

  1. Is Ollama running? Start it with ollama serve.
  2. Is the URL correct? The default is http://localhost:11434/v1. Override with OLLAMA_BASE_URL or ollama_base_url in the config file.
  3. Is the model pulled? Run ollama pull llama3.1 (or your target model) before using it with Trurlic.

Custom provider base URL missing

Section titled “Custom provider base URL missing”

Symptom: trurlic design -p custom fails with “custom provider requires CUSTOM_BASE_URL.”

Solution: Set the base URL via environment variable or config file:

Terminal window
export CUSTOM_BASE_URL="http://my-server:8080/v1"

Or in ~/.config/trurlic/config.toml:

custom_base_url = "http://my-server:8080/v1"

Component not found

Section titled “Component not found”

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

Cause: The component name doesn’t match any file in .trurlic/components/.

Solution: Check exact spelling. Component names are kebab-case. Use trurlic status to list all components. Use project (not a component name) for project-wide decisions.

Decision write rejected

Section titled “Decision write rejected”

Symptom: record_decision returns a validation error.

Common causes:

  • Component doesn’t exist — the referenced component must be added first via add_component.
  • Dangling edge — depends_on or constrains references a decision name that doesn’t exist.
  • Cycle detected — the proposed DependsOn edge would create a cycle.
  • Reserved name — project and all are reserved and cannot be used as component names.

Map won’t open

Section titled “Map won’t open”

Symptom: trurlic map starts the server but the browser doesn’t open.

Solution: Use --no-open and navigate manually:

Terminal window
trurlic map --no-open
# Copy the printed URL to your browser

On headless or WSL environments, opener may fail silently. The URL is always printed to stdout.

Bootstrap finds nothing

Section titled “Bootstrap finds nothing”

Symptom: Bootstrap completes but records zero or few decisions.

Cause: The agent may not have access to your source code, or the project is too small for meaningful extraction.

Solution: For direct bootstrap (-p), ensure the LLM can see your source files. For agent bootstrap, verify the agent has file read access. Consider running trurlic design interactively instead for smaller projects.

Session recovery

Section titled “Session recovery”

Symptom: A design session was interrupted and you want to continue.

Solution: Design sessions are persisted in .trurlic/.state/sessions/. Resume with:

Terminal window
trurlic design <component> --continue

If session files are corrupted, delete .trurlic/.state/sessions/ and start fresh. Decisions already recorded to .trurlic/decisions/ are unaffected — only the session progress is lost.

Getting help

Section titled “Getting help”