Troubleshooting
When something's wrong, start here. The top failure modes with recovery steps.
The fastest first move when something looks off:
vpd doctorRead-only. Prints daemon identity, control-plane endpoints, relay state, config source path, and recovery hints. It does not repair anything. It tells you where to look.
If vpd doctor looks fine, work down this list:
Daemon won't connect
vpd status shows offline. Relay disconnected. JWT errors.
Pairing fails or loops
vpd pair hangs. Browser doesn't return. Code expires before approval.
Agent pauses, no inbox item
The agent stopped but nothing showed up in inbox. The hook didn't fire.
Relay handshake errors
Self-hosters: JWT validate fails, Noise handshake rejected.
Tenant context errors
428, 409, 403 from tenant endpoints. Org switching feels stuck.
Debug recipes
vpd logs, vpd doctor, vpd status. Common diagnostic workflows.
Quick reference
| Symptom | Most likely cause | Page |
|---|---|---|
vpd status says relay disconnected | JWT expired or wrong relay URL | Daemon won't connect |
Browser opens to /pair but never approves | Code expired (15 min TTL) | Pairing fails |
Agent paused but /inbox is empty | Hook bridge not installed | Agent pauses, no inbox |
| Self-hosted relay rejects all connections | RELAY_JWKS_URL unreachable | Relay handshake errors |
| Created new org, every page says "Forbidden" | Tenant context not set after switch | Tenant context errors |
| Phone push never arrives | PWA install required on iOS | Mobile experience |
vpd update failed | Network issue or npm permissions | Debug recipes |
If nothing here helps, email us with the output of vpd doctor --json and we'll dig in.