Troubleshooting

Common failure symptoms, probable causes, and fixes.

---

Daemon startup failures

Symptom	Probable cause	Fix
vlx daemon exits immediately	Missing env var (ADO_PAT, telegram tokens) or vlx.yaml not found / invalid	Run bash setup/check-prereqs.sh; re-read the error message and re-source env vars
Error: unknown adapter type "..."	Typo in adapters.* config key	Check adapters.tracker, adapters.human_channel, etc. Valid values are listed in Configure
Config validation failed at startup	Unknown key in vlx.yaml or wrong type	The error message names the offending key; fix it and restart
Daemon immediately exits with integrity_check failed	state.db is corrupt	See Operations — Database restore

---

ADO polling issues

Symptom	Probable cause	Fix
ADO poll returns 401	PAT expired or wrong scope	Regenerate with Work Items R/W + Code R/W; update env var; restart daemon
Daemon polls but never picks up a story	Story missing the vlx tag, or assigned to the wrong user	Check the tag; check ado.bot_assignee in vlx.yaml vs the PAT owner; default is @Me (PAT owner)
Daemon picks up story but immediately fails	Story work item has no description or title	Add a title and description in ADO before assigning

---

Telegram issues

Symptom	Probable cause	Fix
Telegram messages never arrive	Wrong group_chat_id sign — groups are negative; supergroups have -100 prefix	Re-derive the chat ID via getUpdates; add the bot to the group
Bot does not respond to commands	User not in authorized_user_ids	Add your Telegram user ID to telegram.authorized_user_ids in vlx.yaml
Approval buttons do nothing	Bot not in forum-mode supergroup, or Topics not enabled	Migrate to a forum-mode supergroup; enable Topics in group settings
Clarification question posted but no reply delivered to agent	state_file path not writable (offset not persisted across restart)	Check telegram.state_file path; ensure daemon process has write access

---

Build / pipeline failures

Symptom	Probable cause	Fix
Daemon stuck on a stage	Crash mid-stage; checkpoint not advanced	/history <storyId> in Telegram for the event trail; check stage checkpoints; use /requeue to retry
Build fails with plan_inconsistent	Architect's plan has AC rows that don't match what Builder can implement	Approve the re-plan the orchestrator sends to Telegram
Review finds critical findings every attempt	Builder is making the same mistake repeatedly	Check agent-brain/CLAUDE.md for a correction; use /restart <storyId> think to re-spec from scratch
Inspector gate fails (bun test exits non-zero)	Tests are failing in the worktree	Check qa-evidence/ in the story PR branch; the test output is committed there
Story auto-escaped 2 times, now needs_review	2 consecutive pre-Ship failures	Use /requeue to give it another attempt, or /cancel to abandon

---

Database issues

Symptom	Probable cause	Fix
state.db integrity failure on startup	Corrupt SQLite	Inspect backups/; run vlx db restore <backup> --yes — there is no auto-rollback
vlx status shows a run stuck in active for hours	Daemon crashed mid-stage; worktree exists but no ACP subprocess	Restart the daemon — recovery runs automatically; if still stuck after restart, use /requeue
Event log seq gap detected	Crash between event write and commit	Run is marked needs_review; use /requeue to attempt recovery from the last checkpoint

---

Git / SCM issues

Symptom	Probable cause	Fix
Branch push fails with 403	ADO PAT missing Code R/W scope	Regenerate PAT with Code R/W; update env var; restart daemon
PR creation fails with "branch already exists as PR"	A previous run opened a PR for this story; worktree was destroyed	Use /restart <storyId> ship to re-open or update the PR
git worktree add fails	.vlx/worktrees/ directory not writable	Check permissions on the worktree root; check runtime.worktree_root in config

---

Auto-merge issues

Symptom	Probable cause	Fix
PR approved but never auto-merged	Story missing auto-merge-ok tag, or trust score below threshold	Check ADO work item tags; run vlx status to see trust score
Auto-merge triggered too early	Cooldown expired before you noticed	Use /vetomerge <storyId> before the cooldown expires; increase auto_merge.cooldown_minutes

---

Diagnostic commands quick reference

vlx status                   # active runs + queue depth
vlx db check                 # SQLite integrity check
vlx memory report            # memory hygiene scan

# In Telegram:
/history <storyId>           # last 30 events
/requeue <storyId>           # revive failed run
/restart <storyId> <stage>   # re-run from stage
/cancel <storyId>            # kill run
/vetomerge <storyId>         # block pending auto-merge

---

Getting more log detail

Set LOG_LEVEL=debug (or trace for maximum verbosity) and restart the daemon:

LOG_LEVEL=debug vlx daemon

Under systemd, add the override:

sudo systemctl edit vlx
# Add:
# [Service]
# Environment="LOG_LEVEL=debug"
sudo systemctl restart vlx
sudo journalctl -u vlx -f