Troubleshooting delivery

For a reproducible receiver failure and recovery experiment, start with See delivery fail and recover.

Didn't receive anything?

Work through these in order:

Is routing activated? Changes take effect only after you click Activate routing in Guided Setup or run agentowl config publish <workspace>. agentowl config diff <workspace> shows unpublished changes.
Is there a route? Every binding needs a route to an endpoint. Messages for a binding without one go to dead letters with reason no_route.
Did the message arrive? Check Inbox in the dashboard, or run:
```
agentowl logs tail acme --channel email --limit 20
```
If the message isn't there, AgentOwl never received it. For email, check the address spelling and that the binding is active. For phone numbers, contact support.
Was it blocked by a policy? Open the event and check policy_result. Only allow events are delivered.
Did delivery fail? Open Webhooks → Failed in the dashboard to see the error, or inspect the event:
```
agentowl events inspect evt_abc123
```

Common delivery errors

Symptom	Cause
Timeout	Your endpoint took longer than 30 seconds. Verify and durably accept first, then run slow agent work in a background worker.
`3xx`	AgentOwl does not follow redirects; redirect responses are terminal. Use the final URL, including `https://` and any trailing slash.
`4xx` / `5xx`	Your app rejected or failed the request. Check your logs for the `X-AgentOwl-Event-Id`.
Same event received several times	Retries after a failure. Deduplicate on `event_id`; see Retries and duplicates.

Dead letters

Events that can't be routed, such as messages for a binding without a route, are kept as dead letters. In the dashboard open Webhooks → Dead Letters, or run:

agentowl deadletter list --tenant acme

Replay an event

Once you've fixed the problem, deliver the event again:

# Enqueue a new event (currently resolves current routes)
agentowl events replay evt_abc123 --mode redrive-dispatch

# Use your current routes (after adding a missing route)
agentowl events replay evt_abc123 --mode re-evaluate-route

# Inspect the stored event without delivering or evaluating current routes
agentowl events replay evt_abc123 --mode simulate

Check provider state

For phone numbers, check that the carrier configuration matches your bindings:

agentowl doctor acme
agentowl drift check acme

If drift is reported, agentowl provider sync acme reapplies the configuration.