> ## Documentation Index > Fetch the complete documentation index at: https://lizamas.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting Liza: Agents, Locks, and State Errors > Diagnose and resolve the most common Liza issues: agent crashes, lock errors, state validation failures, worktree problems, and integration failures. Most Liza problems fall into a small number of categories: agents that crash or collide, lock contention on shared state, invalid state from manual edits or version mismatches, worktree inconsistencies, and integration branch conflicts. This page walks you through each category with concrete diagnostic commands and step-by-step fixes. ## Diagnostic Checklist Before diving into a specific issue, run these four commands in order. They surface 80% of problems immediately. **1. Check system status** ```bash theme={null} liza status ``` Confirms the system mode (`RUNNING`, `PAUSED`, `STOPPED`, `CIRCUIT_BREAKER_TRIPPED`), sprint state (`IN_PROGRESS`, `CHECKPOINT`, `COMPLETED`), registered agents, and task summary. If mode is not `RUNNING` or sprint is not `IN_PROGRESS`, that is likely your root cause. **2. Validate state** ```bash theme={null} liza validate ``` Runs 43+ invariant checks against `.liza/state.yaml`. Validation errors include the field name, task ID, and a description of the violated rule. Fix errors before restarting agents. **3. Inspect agent output logs** ```bash theme={null} ls .liza/agent-outputs/ tail -50 .liza/agent-outputs/-.txt tail -20 .liza/agent-outputs/-.err ``` Agent output logs are the primary diagnostic tool. They contain everything the provider CLI printed — prompts, tool calls, errors, and exit messages. Check `.err` files for provider startup failures. **4. Open the TUI** ```bash theme={null} liza tui ``` The TUI shows live agent status, recent alerts, and available actions. It also auto-triggers circuit breaker detection and auto-repairs missing agent roles when `LIZA_AUTO_REPAIR_AGENT_POOL` is enabled (the default). *** ## Issue Categories > [accordion] Agent Issues > > ### COLLISION: agent already registered > > **Error:** > > ``` > COLLISION: planner-1 already registered until 2026-01-20T09:53:55Z > ERROR: Failed to register agent planner-1 (collision?) > ``` > > **Cause:** The agent was killed (Ctrl+C, SIGKILL, crash) before it could unregister. The stale entry persists in `state.yaml` until the lease expires. > > **Fix — recover and respawn in one command:** > > ```bash theme={null} > liza recover-agent planner-1 --cli claude > # Releases task claims, removes worktree, deletes agent, then respawns > ``` > > **Fix — recover without respawn:** > > ```bash theme={null} > liza recover-agent planner-1 > liza agent planner --agent-id planner-1 --cli claude > ``` > > **Fix — use a different agent ID:** > > ```bash theme={null} > liza agent planner --agent-id planner-2 --cli claude > ``` > > **Fix — wait for lease expiry:** The error message shows when the lease expires (`registered until `). After that time, registration succeeds automatically. > > **Prevention:** Use `liza pause` before stopping agents. Paused agents exit gracefully at their next heartbeat check rather than being killed mid-operation. > > *** > > ### Agent timeout (execution exceeds time limit) > > **Symptoms:** > > * Agent shows `WORKING` or `REVIEWING` status for an extended period > * Logs contain: `Agent execution timeout (CLI may be hung, will retry)` > * Agent status automatically resets to `IDLE` after timeout > > **Default timeouts by role:** > > | Role | Timeout | > | - | - | > | Code Reviewer | 30 minutes | > | Coder | 2 hours | > | Planner | 4 hours | > > **Expected behavior:** The supervisor kills the CLI process, resets the agent to `IDLE`, and retries after a 5-second delay. A single timeout is self-recovering — you do not need to intervene. > > **When to investigate:** If the same task causes repeated timeouts, the underlying task or test is problematic. Check `.liza/agent-prompts/` for the agent's last bootstrap prompt and `.liza/agent-outputs/` for what it was attempting. If timeouts recur on the same task, mark it blocked: > > ```bash theme={null} > liza mark-blocked > liza assess-blocked > ``` > > *** > > ### Agent stuck in loop, not claiming tasks > > **Diagnosis:** > > ```bash theme={null} > tail -f coder-1.log > # "Waiting for claimable tasks..." → No claimable tasks available > # "Task task-1 blocked on dependencies" → Dependencies not yet terminal > ``` > > **Common causes and fixes:** > > | Symptom in logs | Cause | Fix | > | - | - | - | > | `Waiting for claimable tasks` | No tasks available | `liza add-task` or advance sprint with `liza resume` | > | `Task blocked on dependencies` | Dependency tasks not terminal | Check `liza get tasks ` | > | No output / idle | System paused | `liza get config.mode` → `liza resume` | > | No output / idle | Sprint at checkpoint | `liza get sprint.status` → `liza resume` | > > *** > > ### Agent stuck in WORKING state > > ```bash theme={null} > # Recover by task ID (recommended) > liza recover-task > > # Recover and discard stale work > liza recover-task --fresh > > # Recover by agent ID > liza recover-agent coder-1 > > # Restart after recovery > liza agent coder --agent-id coder-1 --cli claude > ``` > > *** > > ### Ghost agent (registered but process is dead) > > **Diagnosis:** > > ```bash theme={null} > liza get agents --format table > # Check process_status, process_status_source, lease_expires > ``` > > **Fix:** > > ```bash theme={null} > liza recover-agent > # or > liza delete agent > ``` > > > [!WARNING] > > > > On Linux, Liza uses procfs identity checks to distinguish a live Liza supervisor from a dead or PID-reused process. In containers or across SSH boundaries, a live host agent can appear as `process_status: stopped` because its PID is not visible from the current namespace. Check `process_status_source` and `process_status_detail` before recovering. A recent heartbeat and growing `.liza/agent-outputs/` are stronger liveness signals than PID status alone. > > *** > > ### Task stuck in BLOCKED state > > **Symptoms:** A task shows status `BLOCKED`. Agents skip it. No agent claims it. > > **Diagnosis:** > > ```bash theme={null} > liza get tasks > # Read blocked_reason, blocked_questions, and depends_on fields > ``` > > **Fix — dependency not yet terminal:** > > Check whether the blocking dependency has been merged: > > ```bash theme={null} > liza get tasks > ``` > > When the dependency reaches a terminal state and every `depends_on` target is directly `MERGED`, unblock the task: > > ```bash theme={null} > liza unblock-task --reason "dependency task-N is now MERGED" > > # Or unblock and assign directly to an available agent > liza unblock-task --reason "ready" --assign-to coder-1 > ``` > > **Fix — wrong dependency edge:** > > If the blocking dependency edge is stale, retarget it without unblocking: > > ```bash theme={null} > liza retarget-dependency --reason "task superseded" > # Task remains BLOCKED until explicitly unblocked > liza unblock-task --reason "dependency updated" > ``` > > **Fix — worktree diverged while blocked:** > > If the integration branch advanced while the task was blocked, rebase the preserved worktree before unblocking: > > ```bash theme={null} > liza unblock-task --rebase-on integration --reason "rebased after fix" > ``` > > **Fix — underlying issue requires orchestrator triage:** > > ```bash theme={null} > liza assess-blocked > ``` > > **Prevention:** Keep tasks small and depend only on the minimum required set. A BLOCKED alert is raised when a task blocks; `liza analyze` will catch repeated BLOCKED patterns as a circuit breaker signal. > [accordion] Lock & Concurrency Issues > > Liza uses file-based locking (`flock`) for safe concurrent state access. Lock errors include a classified type to help you target the right fix. > > ### Lock error classification > > | Error type | Meaning | > | - | - | > | `lock error (timeout)` | Failed to acquire lock within the timeout window | > | `lock error (stale)` | Owner metadata references a dead process | > | `lock error (disk_full)` | No space left on device | > | `lock error (permission)` | Permission denied on lock file | > | `lock error (filesystem)` | I/O error or filesystem issue | > > *** > > ### Lock timeout — failed to acquire lock > > **Diagnosis:** > > ```bash theme={null} > ps aux | grep liza # Check for running liza processes > lsof .liza/state.yaml.lock # Process holding the kernel flock (if visible) > cat .liza/state.yaml.lock.owner.json # Best-effort diagnostic owner metadata > ``` > > **Fixes by cause:** > > | Cause | Fix | > | - | - | > | Holder is alive and working | Wait 30–60 seconds and retry | > | Holder appears hung | Stop the owning `liza` process | > | High contention from many agents | Reduce to 1–3 agents per role | > | Slow network filesystem | Move `.liza/` to a local SSD | > > > [!NOTE] > > > > The `.lock` file and `.lock.owner.json` may remain on disk after a successful operation — their presence alone does not mean a lock is currently held. `flock` is the mutual exclusion mechanism; file presence is diagnostic metadata only. Do not delete lock files based on PID metadata alone without confirming no `liza` process is running. > > *** > > ### Disk full > > ```bash theme={null} > df -h .liza/ # Check available disk space > df -i .liza/ # Check available inodes > du -sh .worktrees/* # Find large worktrees consuming space > ``` > > **Free space:** > > ```bash theme={null} > liza wt-delete # Remove merged worktrees > git gc --aggressive --prune=now # Compact git objects > ``` > > *** > > ### Permission denied on lock file > > ```bash theme={null} > ls -la .liza/state.yaml.lock* # Check lock file permissions > ls -ld .liza/ # Check directory permissions > ``` > > **Fix — correct ownership:** > > ```bash theme={null} > sudo chown -R $(whoami):$(id -gn) .liza/ > ``` > > **Common causes:** Running `liza` as root and then as a regular user, or NFS mounts with restrictive permissions. > > *** > > ### "State modified by another process, retry" > > This message is normal and expected. Liza uses a three-phase claim pattern that detects write races and retries automatically. If you see this message persisting, too many agents may be competing for the same tasks — reduce parallel agents per role. > [accordion] State Validation Failures > > Run `liza validate` to get the exact rule that failed and the task or agent ID involved. Most validation failures have a targeted fix. > > *** > > ### Missing required field > > **Error:** `INVALID: missing required field 'sprint'` > > **Cause:** The state file was manually edited, created with an old `liza init`, or truncated. > > **Fix:** Add the missing section according to the blackboard schema. Use `liza validate` to confirm which fields are missing, then add them. Prefer using a Liza CLI command for the change when one exists rather than editing `state.yaml` directly. > > *** > > ### Task status invariant violation > > **Error:** `INVALID: IMPLEMENTING_CODE task without assigned_to: task-1` > > Tasks in executing states must have `assigned_to`, `worktree`, and a valid `lease_expires`. Tasks in reviewing states must have `reviewing_by` and `review_commit`. > > **Fix — reset to initial pipeline state:** > > Run `liza validate` to identify the violated invariant, then either: > > * Use `liza recover-task ` to reset the task cleanly, or > * Run `liza migrate` to normalize role names and fix common invariant violations from version mismatches > > ```bash theme={null} > liza migrate > liza validate > ``` > > *** > > ### Circular dependency detected > > **Identify the cycle:** > > ```bash theme={null} > liza get tasks --format table > # Look at depends_on for each task to trace the cycle > # Example cycle: task-1 → task-2 → task-3 → task-1 > ``` > > **Fix — retarget the offending dependency:** > > ```bash theme={null} > liza retarget-dependency task-3 task-1 task-4 --reason "break circular dependency" > liza validate > ``` > > *** > > ### Spec file not found > > **Fix — create the spec file:** > > ```bash theme={null} > mkdir -p specs > cat > specs/vision.md << 'EOF' > # Vision: Project Name > ## Goal > [What you want to build] > ## Requirements > [List of requirements] > ## Success Criteria > [How to verify completion] > EOF > ``` > > Or update the `spec_ref` field on the task using `liza validate` to find the task ID, then use line-level text edits (not a YAML serializer) to update the reference. > [accordion] Worktree Issues > > ### Worktree directory not found > > **Error:** `INVALID: IMPLEMENTING task has worktree=.worktrees/ but directory does not exist` > > **Fix — recreate the worktree:** > > ```bash theme={null} > # Get the task's base_commit > liza get tasks > > # Recreate the worktree from that commit > git worktree add .worktrees/ -b task/ > ``` > > **Fix — reset the task if work was lost:** > > ```bash theme={null} > liza recover-task --fresh > # Discards the branch and worktree; task returns to its pipeline initial state > ``` > > *** > > ### Worktree already exists > > ```bash theme={null} > # Option 1: Full task recovery (cleans worktree + branch + state) > liza recover-task --force > > # Option 2: Delete and recreate (task must be in a terminal state) > liza wt-delete > liza wt-create > ``` > > *** > > ### Branch already checked out / cannot remove worktree > > ```bash theme={null} > # Force-remove the stuck worktree > git worktree remove .worktrees/ --force > ``` > > *** > > ### Worktree directory is dirty > > ```bash theme={null} > cd .worktrees/ > git status > > # Save progress > git add . && git commit -m "WIP: save progress before recovery" > > # Stash changes > git stash > > # Discard changes (destructive) > git reset --hard HEAD > ``` > > *** > > ### Invalid reference: task/\ > > The task branch does not exist in git. > > ```bash theme={null} > # List task branches > git branch -a | grep task/ > > # Recreate from base_commit (get it from liza get tasks ) > git branch task/ > ``` > [accordion] Integration Issues > > ### Integration branch missing > > The integration branch is created by `liza init`. If it is missing, recreate it: > > ```bash theme={null} > git branch integration main > ``` > > Then re-run `liza init` or manually set the branch reference in `.liza/state.yaml` if the integration branch name differs from the default. > > *** > > ### Task marked INTEGRATION\_FAILED > > When an approved task's merge to the integration branch fails due to a conflict or test failure, Liza transitions the task to `INTEGRATION_FAILED`, aborts the merge, and preserves the worktree for resolution. > > **Diagnosis:** > > ```bash theme={null} > liza get tasks # Check failure details > cd .worktrees/ && git status # See conflicted files > ``` > > **Fix — merge conflict:** > > 1. Edit files with conflict markers (`<<<<<<<` / `=======` / `>>>>>>>`) > 2. Stage and commit the resolution > 3. Claim the task as a coder with `integration_fix: true` > 4. Resubmit for review > > **Fix — test failure:** > > 1. Run your test suite inside the worktree: `go test ./...` (or equivalent) > 2. Fix the failing tests and commit > 3. Claim the task and resubmit for review > > The fix goes through normal review before the merge retries. > > **Prevention:** Keep task scope small. Merge the integration branch into task branches frequently to reduce divergence. > [accordion] Initialization Issues > > ### Error: .liza already exists > > **Option 1 — continue with existing state:** > Just start your agents. Liza is stateful; the existing `.liza/` directory contains your sprint history. > > **Option 2 — reset completely:** > > ```bash theme={null} > rm -rf .liza .worktrees > liza init "New goal" > ``` > > **Option 3 — force reinitialize:** > > ```bash theme={null} > liza init "New goal" --force > ``` > > *** > > ### Symlink creation fails on Windows > > **Error:** > > ``` > Warning: failed to create CLAUDE.md symlink: symlink ... A required privilege is not held by the client. > ``` > > Liza uses symbolic links in several places. Windows requires Developer Mode or Administrator privileges to create them. > > | Command | Links created | Impact if missing | > | - | - | - | > | `liza init` | `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` → `~/.liza/CORE.md` | Agents cannot find the behavioral contract | > | `liza setup` | Skill links in CLI config dirs → `~/.liza/skills/` | Agents cannot load skills | > | `liza setup` | CLI-specific prompt files | CLI prompt activation fails | > > **Fix — enable Developer Mode (recommended):** > Settings → System → For developers → toggle Developer Mode on. Then re-run `liza setup` and `liza init`. > > **Fix — run elevated:** > Open your terminal as Administrator and re-run the command. > > > [!NOTE] > > > > WSL2 is the recommended environment for Liza on Windows. Native Windows support is limited by the symlink restriction. Using WSL2 eliminates this issue entirely. > > *** > > ### Error: specs/vision.md required > > ```bash theme={null} > mkdir -p specs > cat > specs/vision.md << 'EOF' > # Vision: Project Name > ## Goal > [What you want to build] > ## Requirements > [List of requirements] > ## Success Criteria > [How to verify completion] > EOF > ``` > > Or initialize without a spec file: > > ```bash theme={null} > liza init "Your goal description" > # The interactive wizard will guide you through goal capture > ``` > [accordion] Performance Issues > > ### 30-second or longer response delays > > **Cause:** `fsnotify` does not work reliably on network filesystems (NFS, SMB). Agents fall back to 30-second polling. > > **Fix:** Move your project to a local filesystem. If that is not possible, accept the polling delay and adjust your `heartbeat_interval` configuration accordingly. > > **Also check:** > > ```bash theme={null} > liza get config.mode # Should be RUNNING > liza get sprint.status # Should be IN_PROGRESS > ``` > > *** > > ### Slow state file reads (>50ms) > > ```bash theme={null} > ls -lh .liza/state.yaml # Check file size (target <1MB) > time liza validate # Time a full state read > ``` > > **Common causes and fixes:** > > | Cause | Fix | > | - | - | > | Large state file | Archive completed tasks | > | Slow disk | Move `.liza/` to an SSD | > | External modifications | Disable Dropbox/editor auto-save on `.liza/` | > > *** > > ### Slow task claims (5–10 seconds) > > Git worktree operations are slow on large repositories. > > **Fix:** Use an SSD. For very large repos, consider sparse checkout: > > ```bash theme={null} > git config core.sparseCheckout true > ``` > > *** > > ### Validation takes more than 5 seconds > > Large task lists or complex dependency graphs slow validation. > > ```bash theme={null} > # Skip spec file existence checks on slow filesystems > liza validate --skip-spec-check > > # Archive terminal tasks to reduce state size > # (use liza delete task for ABANDONED/SUPERSEDED tasks no longer needed) > ``` > [accordion] Provider Quota & Availability Issues > > ### Provider quota exhausted > > **Symptoms:** All agents using a provider stop. System mode is still `RUNNING`. Signal file `.liza/provider-quota-exhausted-` exists. > > **Diagnosis:** > > ```bash theme={null} > ls .liza/provider-quota-exhausted-* > cat .liza/alerts.log | grep "PROVIDER QUOTA" > ``` > > **Fix:** > > ```bash theme={null} > liza pause > liza resume > # Resume clears quota signals and restarts the sprint > # Then restart your agents > liza agent coder --cli claude > ``` > > > [!NOTE] > > > > `liza resume` alone fails if the system is still `RUNNING`. You must pause first to transition to `PAUSED`, then resume to clear quota signals. > > *** > > ### Provider unavailable > > **Symptoms:** Agents stop before doing useful work. Signal file `.liza/provider-unavailable-` exists. `.liza/agent-outputs/*.err` shows startup errors. > > **Fix:** > > 1. Repair the provider environment (for Codex: ensure `~/.codex/sessions` is accessible) > 2. Run `liza pause` and `liza resume` to clear the signal > > *** > > ### Circuit breaker tripped > > **Symptoms:** System mode is `CIRCUIT_BREAKER_TRIPPED`. Sprint is at `CHECKPOINT`. `liza analyze` reports the triggering pattern. > > **Fix:** > > 1. Read the circuit breaker report in `.liza/` > 2. Investigate the root cause (crash loop, validation failure, repeated integration conflicts) > 3. Fix the underlying issue > 4. Resume to clear the breaker: > ```bash theme={null} > liza resume > ``` > > After `liza resume` clears a tripped circuit breaker (`status: OK`, `current_trigger: null`), historical anomalies that triggered it are acknowledged. Future `liza analyze` runs count only anomalies after the latest cleared trigger. *** ## Getting Help If the above steps do not resolve your issue, generate a debug report to share with support or your team. **1. Generate a debug report** ```bash theme={null} cat > debug-report.txt << 'EOF' === Liza Debug Report === EOF echo "Version: $(liza version)" >> debug-report.txt echo "State Validation:" >> debug-report.txt liza validate 2>&1 >> debug-report.txt echo "Tasks:" >> debug-report.txt liza get tasks --format table 2>&1 >> debug-report.txt echo "Agents:" >> debug-report.txt liza get agents --format table 2>&1 >> debug-report.txt echo "Worktrees:" >> debug-report.txt git worktree list >> debug-report.txt echo "Recent Alerts:" >> debug-report.txt tail -50 .liza/alerts.log 2>/dev/null >> debug-report.txt echo "Lock Status:" >> debug-report.txt ls -la .liza/state.yaml.lock* 2>&1 >> debug-report.txt echo "Processes:" >> debug-report.txt ps aux | grep liza >> debug-report.txt ``` **2. Capture liza status output** ```bash theme={null} liza status --format json >> debug-report.txt ``` **3. Capture liza validate output** ```bash theme={null} liza -v validate >> debug-report.txt 2>&1 ``` **4. Check activity and alert logs** ```bash theme={null} cat .liza/log.yaml # Full activity log cat .liza/alerts.log # Alert history ls .liza/agent-prompts/ # Generated agent bootstrap prompts ``` > [!TIP] > > Use the `/liza-logs` skill inside any pairing session with Claude or Codex to get LLM-assisted log analysis. It cross-correlates agent output files, identifies patterns, and proposes fixes. You can also use the browser-based analyzer at `~/.liza/skills/liza-logs/tools/liza-session-analyzer.html` by dragging and dropping your `.liza/agent-outputs/*.txt` files. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.