Troubleshooting
Find out whether a problem is a safety stop, a disconnected service, or a configuration issue.
On this page
Start with the local facts
Run these from the same environment and LEASH_HOME as your agent. Record the error reason, session ID and reservation ID if present. Do not include provider keys, webhook URLs or session cookies in a support request.
leash doctor
leash status --jsonProxy down or no sessions visible
Start leash start, or use leash run to start the proxy with the agent. Check that your agent is actually using the configured endpoint. A directly launched agent with an untouched configuration can bypass Leash.
For dashboard visibility, inspect device credentials and run leash sync --device. A local-only ledger is not automatically visible in a hosted workspace. Check that the selected browser workspace matches the device's workspace.
A request was blocked earlier than expected
Inspect spent plus reserved amounts. Admission reserves maximum priced output, not just the most likely answer length. An interrupted reservation remains conservative until you verify the provider charge.
Check workspace, repository and session caps, model allowlists, panic, repeat detection and shared-mode connectivity. Resume does not remove higher-level budgets. Do not erase state or silently disable shared enforcement to work around a stop.
A remote kill has not reached a machine
Settings → Devices shows last seen and acknowledgement state. Ensure leash start is running with the device's LEASH_HOME. LEASH_OFFLINE=1 or LEASH_SYNC=0 pauses transport. A revoked token returns 401 and must be replaced through an authorized enrollment flow.
Remote delivery is not instantaneous when a machine is offline. If you have local access, use leash kill --all on that machine. Shared mode rejects new calls when its central admission service cannot be reached.
An alert or weekly email did not arrive
Inspect alertsPending in local status and the workspace's email preferences. Check active plan access, a verified email address, opt-in state and configured channel credentials. Restart after correcting environment-based configuration.
An accepted email or webhook can still be delayed or filtered by its destination. Operators must verify real sender authentication and inbox delivery. The application does not configure mail forwarding or DNS for you.