Troubleshooting

Start with doctor#

Doctor should repair missing hooks, stale hook paths, missing shell env vars, unwritable queue/cache directories, and stale policy cache when possible.

agentlint doctor --fix

Check status#

Status should show installed version, detected agents, AgentChute connectivity, queued events, last upload, policy version, and cache freshness.

agentlint status
agentlint policy explain
agentlint queue status

Common issues#

• 01No events: run agentlint test --flush from a repo with hooks installed.
• 02API unreachable: verify AGENTCHUTE_API_URL and server availability.
• 03Policy stale: run agentlint policy refresh outside the hook path.
• 04Wrong workspace: rotate the local key and rerun onboarding.