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

   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

   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

   ls .liza/agent-outputs/
   tail -50 .liza/agent-outputs/<agent-id>-<timestamp>.txt
   tail -20 .liza/agent-outputs/<agent-id>-<timestamp>.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

   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

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:

liza recover-agent planner-1 --cli claude
# Releases task claims, removes worktree, deletes agent, then respawns

Fix — recover without respawn:

liza recover-agent planner-1
liza agent planner --agent-id planner-1 --cli claude

Fix — use a different agent ID:

liza agent planner --agent-id planner-2 --cli claude

Fix — wait for lease expiry: The error message shows when the lease expires (registered until <timestamp>). 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:

liza mark-blocked <task-id>
liza assess-blocked <task-id>

---

​

Agent stuck in loop, not claiming tasks

Diagnosis:

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 <dep-id>
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

# Recover by task ID (recommended)
liza recover-task <task-id>

# Recover and discard stale work
liza recover-task <task-id> --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:

liza get agents --format table
# Check process_status, process_status_source, lease_expires

Fix:

liza recover-agent <agent-id>
# or
liza delete agent <agent-id>

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:

liza get tasks <task-id>
# Read blocked_reason, blocked_questions, and depends_on fields

Fix — dependency not yet terminal:

Check whether the blocking dependency has been merged:

liza get tasks <dep-id>

When the dependency reaches a terminal state and every depends_on target is directly MERGED, unblock the task:

liza unblock-task <task-id> --reason "dependency task-N is now MERGED"

# Or unblock and assign directly to an available agent
liza unblock-task <task-id> --reason "ready" --assign-to coder-1

Fix — wrong dependency edge:

If the blocking dependency edge is stale, retarget it without unblocking:

liza retarget-dependency <task-id> <old-dep-id> <new-dep-id> --reason "task superseded"
# Task remains BLOCKED until explicitly unblocked
liza unblock-task <task-id> --reason "dependency updated"

Fix — worktree diverged while blocked:

If the integration branch advanced while the task was blocked, rebase the preserved worktree before unblocking:

liza unblock-task <task-id> --rebase-on integration --reason "rebased after fix"

Fix — underlying issue requires orchestrator triage:

liza assess-blocked <task-id>

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.

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:

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

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

df -h .liza/          # Check available disk space
df -i .liza/          # Check available inodes
du -sh .worktrees/*   # Find large worktrees consuming space

Free space:

liza wt-delete <merged-task-id>     # Remove merged worktrees
git gc --aggressive --prune=now     # Compact git objects

---

​

Permission denied on lock file

ls -la .liza/state.yaml.lock*      # Check lock file permissions
ls -ld .liza/                       # Check directory permissions

Fix — correct ownership:

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.

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 <task-id> to reset the task cleanly, or
• Run liza migrate to normalize role names and fix common invariant violations from version mismatches

liza migrate
liza validate

---

​

Circular dependency detected

Identify the cycle:

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:

liza retarget-dependency task-3 task-1 task-4 --reason "break circular dependency"
liza validate

---

​

Spec file not found

Fix — create the spec file:

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.

Worktree Issues

​

Worktree directory not found

Error: INVALID: IMPLEMENTING task <task-id> has worktree=.worktrees/<task-id> but directory does not exist

Fix — recreate the worktree:

# Get the task's base_commit
liza get tasks <task-id>

# Recreate the worktree from that commit
git worktree add .worktrees/<task-id> -b task/<task-id> <base-commit>

Fix — reset the task if work was lost:

liza recover-task <task-id> --fresh
# Discards the branch and worktree; task returns to its pipeline initial state

---

​

Worktree already exists

# Option 1: Full task recovery (cleans worktree + branch + state)
liza recover-task <task-id> --force

# Option 2: Delete and recreate (task must be in a terminal state)
liza wt-delete <task-id>
liza wt-create <task-id>

---

​

Branch already checked out / cannot remove worktree

# Force-remove the stuck worktree
git worktree remove .worktrees/<task-id> --force

---

​

Worktree directory is dirty

cd .worktrees/<task-id>
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/<task-id>

The task branch does not exist in git.

# List task branches
git branch -a | grep task/

# Recreate from base_commit (get it from liza get tasks <task-id>)
git branch task/<task-id> <base-commit>

Integration Issues

​

Integration branch missing

The integration branch is created by liza init. If it is missing, recreate it:

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:

liza get tasks <task-id>                   # Check failure details
cd .worktrees/<task-id> && 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.

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:

rm -rf .liza .worktrees
liza init "New goal"

Option 3 — force reinitialize:

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.

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

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:

liza init "Your goal description"
# The interactive wizard will guide you through goal capture

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:

liza get config.mode       # Should be RUNNING
liza get sprint.status     # Should be IN_PROGRESS

---

​

Slow state file reads (>50ms)

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:

git config core.sparseCheckout true

---

​

Validation takes more than 5 seconds

Large task lists or complex dependency graphs slow validation.

# Skip spec file existence checks on slow filesystems
liza validate --skip-spec-check

# Archive terminal tasks to reduce state size
# (use liza delete task <id> for ABANDONED/SUPERSEDED tasks no longer needed)

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-<provider> exists.

Diagnosis:

ls .liza/provider-quota-exhausted-*
cat .liza/alerts.log | grep "PROVIDER QUOTA"

Fix:

liza pause
liza resume
# Resume clears quota signals and restarts the sprint
# Then restart your agents
liza agent coder --cli claude

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-<provider> 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:
   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

   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

   liza status --format json >> debug-report.txt
   
3. Capture liza validate output

   liza -v validate >> debug-report.txt 2>&1
   
4. Check activity and alert logs

   cat .liza/log.yaml         # Full activity log
   cat .liza/alerts.log       # Alert history
   ls .liza/agent-prompts/    # Generated agent bootstrap prompts
   

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.