Skip to main content

​
Troubleshoot a fleet

​
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.
  3. Apply the fix named by the stable error identifier. UZ-AGT-008 points to invalid TRIGGER.md data. UZ-BUNDLE-003 points to missing workspace secrets. UZ-WH-010 points to a signature mismatch. UZ-AGT-012 points to a fleet that cannot accept work.
  4. Retry the original event once. Lifecycle commands do not retry network failures. 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 SKILL.md steps numbered and keep tool names aligned with TRIGGER.md. Store stable provider event identifiers for duplicate protection. Use fleet budgets to bound cost. Check the activity stream after every bundle update.