Skip to main content

​
Symptom

​
Why it happened

Most failures come from authentication, workspace selection, webhook signatures, missing secrets, tool access, or budget limits. Every API error carries a stable error identifier and request identifier. Use both values when comparing a response with the error registry.

​
How to fix it

  1. Check client and workspace health.
  2. Read the fleet’s recent errors. <FLEET_ID> comes from agentsfleet list.
    In the dashboard, open the failed event and click Copy diagnostic. The copy contains its event identifier, failure class, and recorded cause. For a reply that stopped early, it also carries safe stream counters when the runner reported them. Share that copy with an operator; the event identifier lets them find the run across multiple runners.
  3. Apply the fix named by the stable error identifier. UZ-REQ-001 from a chat or Save points to an invalid Definition field. A Save that stays installing names each missing secret or grant. UZ-WH-010 points to a signature mismatch. UZ-AGT-012 points to a fleet that cannot accept work.
  4. When a connected GitHub App sends nothing, check the subscription. An App delivery reaches every fleet in the workspace, so each fleet says which repositories it wants. A fleet that names none subscribes to none. Open the delivery in GitHub → Settings → Integrations → the App → Recent Deliveries. A body of {"ignored": "UZ-WH-022"} under a 200 means the event arrived and matched no fleet. The status is green either way, so read the body. Set repositories beside "source": "github" in the webhook trigger. Use owner/repository; case does not matter. Then check the fleet’s integration grant:
  5. Retry the original event once. Lifecycle commands send a write again only when the connection was refused or the server declined to run it. A reset after sending or a timeout surfaces the error. Provider webhooks follow the provider’s own retry policy.

​
How to prevent it

Run agentsfleet doctor before installation. Test one manual message before registering a webhook. Keep the fleet’s instruction steps numbered, and name only tools its Definition declares. Store stable provider event identifiers for duplicate protection. Use fleet budgets to bound cost. Check the activity stream after every applied setup change.