Reference
Troubleshooting
Deterministic recovery procedures for guard rejections, SQLite concurrency, and state rehydration using the AXI CLI.
Guard expression evaluation failures
Symptom: A transition fails to fire. The state machine holds deterministically in the current state and writes a GUARD_FAILED event to the ledger. In AXI CLI mode, exit code 2 is returned with inline recovery instructions.
Root cause
The guard expression in skill.yaml evaluates a context key that is undefined, type-mismatched (e.g. comparing string "0" to numeric 0), or unsatisfied by current facts.
- 1
Inspect the guard contract
Run
npx -y @reactive-skills/axi inspect skills/<skill>to review defined transitions and guard predicates. - 2
Check evaluated context snapshot
Run
npx -y @reactive-skills/axi events <skill> 5to inspect the exact context facts evaluated during the failure. - 3
Correct assertions and re-emit
Resolve code assertions or supply missing context payload, then re-dispatch the signal.
npx -y @reactive-skills/axi emit my-skill RECOVER_STATEEvent store lock / SQLite busy errors
Symptom: The runtime returns SQLITE_BUSY or "database is locked". Event appends halt, and projections pause.
Concurrent access
Multiple concurrent processes (e.g. an unclosed test task and an active MCP daemon) are writing to the same skill events.db database file.
- 1
Terminate orphan processes
Kill orphan node processes holding open file descriptors on
.reactive/skills/<skill>/events.db. - 2
Run database checkpoint recovery
Run
npx -y @reactive-skills/axi rebuild-sqlite <skill>to reconcile SQLite from the durable JSONL log. - 3
Isolate CI workers
Ensure parallel CI jobs run within isolated workspaces or set separate skill directory paths.
State rehydration after process termination
Symptom: After an abrupt process termination, inspecting the skill shows initial state instead of the last active state.
Because the event store is authoritative, the runtime rehydrates state by replaying all append-only events. If a process died before flushing, replay deterministically halts at the last committed event.
npx -y @reactive-skills/axi events my-skill 50