An agent run failed — how do I debug?
2 min · 5 steps
Open the Runs tab + drill into the failing node. Every input + output is captured.
Avery's agent runtime is replayable: every node's input + output is captured to a per-agent ledger. A failure is reading the trace, not guessing.
Steps
- Open the Runs tab.
On the agent's workspace.
- Click the failed run.
The trace expands. Failed nodes are marked with a red icon; succeeded nodes are green.
- Inspect the failing node's error panel.
Each node row has an expandable details section. Look at the input the node received + the error message. Common patterns: missing connector binding (auth failed), invalid argument (the upstream node returned an unexpected shape), timeout (provider slow).
- Or let 'Fix with AI' do it for you.
A failed run shows a 'Fix with AI' button. It reads the failing node's trace, proposes a concrete one-click fix, applies it, and reruns to verify — looping until the run is clean. If the local model can't crack it, it ESCALATES to your configured cloud model automatically: in cloud-only routing this is silent; in local-first mode (the default) it asks first with a 'Consult frontier model' button so your config only leaves the machine when you click it (if no cloud key is set, an inline form lets you add one). Each escalation + each applied fix is recorded in the Activity stream.
- Fix the underlying cause + rerun.
If it was a missing connector → the agent's Overview will show the relevant setup task. If it was a provider issue → check the connector's Test button on the global Connectors page. If it was an upstream-shape issue → open the Builder + verify the input mapping on the failing node.
Live recipes need the desktop
This article is a static preview. The in-app Help sidecar inside Avery NXR can fire each step against your live project — install the desktop to use it interactively.