> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsfleet.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot a fleet

> Find and fix common fleet failures.

# Troubleshoot a fleet

## Symptom

| Symptom                          | First check                         |
| -------------------------------- | ----------------------------------- |
| Every command fails              | Run `agentsfleet doctor`.           |
| A webhook does not create a run  | Read recent webhook events.         |
| A run starts and fails           | Read the activity stream error.     |
| A fleet returns the wrong result | Compare tool calls with `SKILL.md`. |
| New runs are blocked             | Check fleet state and budgets.      |

## 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.

   ```bash theme={"theme":"vesper"}
   agentsfleet doctor
   ```

   ```text theme={"theme":"vesper"}
   <varies>
   ```

2. Read the fleet's recent errors.

   `<FLEET_ID>` comes from `agentsfleet list`.

   ```bash theme={"theme":"vesper"}
   agentsfleet events <FLEET_ID> --since 1h --json
   ```

   ```text theme={"theme":"vesper"}
   <varies>
   ```

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.