Failure modes
Common symptoms
| Symptom | Likely cause | First check |
|---|---|---|
| 403 from API | Wrong actor credential or workspace scope. | Check whether you need bearer JWT or x-api-key. |
| Agent online but not receiving work | Wrong workspace, project, team, role, or queue filter. | List the agent and inspect its inbox in the same workspace. |
| Terminal opens wrong session | Stale console-router route or reused serve port. | Compare agent ID, serve port, and router inventory. |
| Workflow stuck after PR merged | Completion evidence not attached to handoff/run. | Open workflow diagnosis and PR comments. |
| Provider login loops | Expired provider auth or sidecar challenge pending. | Check provider sidecar status before respawning agents. |
| Docs page returns homepage | Static route missing from deployed bundle. | Verify docker/site/docs/.../index.html is deployed. |
Safe debugging
Do not leak secrets while debugging
midfleet config redact --json
midfleet config doctor
midfleet internal status
midfleet internal inbox --name <agent> --jsonWhen sharing evidence, summarize command results and redact tokens, API keys, provider credentials, relay secrets, and service-token values.