V1 Failure Modes Runbook

  1. Use this page when Klawforge crashes, fails to launch, exhausts a quota, or answers oddly. It is the central symptom-to-fix table — five-minute path to working again.
  2. Each section follows the same template: Symptom → Root cause → Diagnose → Fix → Reference.
  3. If none of these resolve it, mail support@klawforge.com with the sidecar log (~/Library/Logs/Klawforge/*.log) and your build version (Settings → Build info).

Covered failure modes (v1)

  • 1. Sidecar failed to start — port conflict, stale binary, architecture mismatch.
  • 2. macOS TCC denied — Music / Downloads / NetworkVolumes / Documents permission flow.
  • 3. License invalid — dev license, customer license, grace period flows.
  • 4. LLM quota exhausted — three-CLI fallback, sublimation pause, recall lexical-only.
  • 5. Brain Health metric anomalies — orphans, subgraphs.
  • 6. Graph view stutter / anomalies — 5000+ nodes, dueling animation.
  • 7. Sublimation not working — auto-trigger, per-entity residue fallback.
  • 8. Memory growing too fast — T3 orphan_prune manual cleanup path.
  • 9. Cross-window / cross-IDE capture failing — klawforge-capture / MCP shim.
  • 10. App refuses to open — Gatekeeper, quarantine xattr, /Applications shadow.