Troubleshooting
Debug the launch path: pairing, worker claims, Slack/GitHub delivery, approvals, and run receipts.
Start with doctor output:
vpd worker doctor --json
vpd status --jsonFor workflow issues, vpd worker doctor --json is usually more useful than the
personal monitor status. It should explain pairing, server, workspace, runner
identity, transport, workspace root, detected agents/tools, and claimability.
Route does not start a run
Slack/GitHub delivered, but no governed run was queued.
Runner won't claim work
Queued run, but the self-hosted worker never picks it up.
Approval or plan revision is stuck
Blocked gate, request changes loop, or revised plan review issue.
Provider receipts are missing
GitHub PR, Slack completion, or external receipt did not appear.
Pairing fails or loops
Pairing code expired, wrong profile, server mismatch, or browser approval issue.
Daemon won't connect
Local daemon offline, relay disconnected, or stale process state.
Tenant context errors
Workspace/team mismatch, stale membership, or wrong active organization.
Debug recipes
Focused commands and support bundle guidance.
Fast Diagnosis
| Symptom | First check |
|---|---|
| Slack/GitHub event arrived but no run exists | Route sync, event type, route conditions, and policy admission. |
| Worker is online but run remains queued | Runner pool/capability mismatch or claim denial. |
| Run starts but blocks forever | Approval gate, revision loop, or unavailable provider grant. Start with Approval or plan revision is stuck. |
Slack posts raw \n | Slack renderer regression; capture run id and Slack timestamp. |
| Slack posts to channel instead of thread | Source Slack timestamp missing, fixture run, or notification target fell back. |
| PR is not created | GitHub App grant, approval state, repo scope, or side-effect denial. See Provider receipts are missing. |
| Completion receipt missing | Worker cleanup/sync failure or provider notification failure. See Provider receipts are missing. |
Support Bundle
Collect:
vpd worker doctor --json > /tmp/vpd-worker-doctor.json
vpd status --json > /tmp/vpd-status.jsonAlso capture:
- workspace and team name;
- workflow id and run id;
- runner name;
- Slack channel/timestamp if relevant;
- GitHub PR/proposal URL if relevant;
- denial code or error message shown in the app.
Do not include raw tokens, pairing codes, private keys, lease tokens, bootstrap tokens, or provider secrets.