Skip to main content

Agent: Error Handling & Node Options

AI calls fail sometimes — a provider hiccups, a rate limit trips. The Agent node has well-defined behaviour for these, and it interacts with n8n's own On Error and Retry On Fail settings, so it's worth knowing how the pieces fit.

The node's own guardrails​

Before any provider call, the Agent node validates its setup — a resolvable agent slug, a valid model and parameters, a present provider credential. If any of that is wrong, it treats the situation as a configuration error: it logs the problem, terminates the run, and raises a NodeOperationError (the error type meaning "this will fail the same way on retry, so don't bother retrying"). These are your setup mistakes, surfaced early and clearly.

When the AI call itself fails​

For a failure of the AI request — a transient provider error — the node uses NodeApiError (meaning "this might succeed on retry") and then follows your n8n settings:

  • On Error: Stop Workflow (recommended), with Retry On Fail on — the node lets n8n retry the step and does not terminate the run yet, because a retry might succeed. Each retry is a fresh attempt (new validation, a new AI call — and yes, new cost — and a new log entry). If n8n eventually exhausts retries and gives up, the platform's reconciler notices the stalled run and marks it failed.
  • On Error: Stop Workflow, with Retry On Fail off — no retry is coming, so the node terminates the run immediately and errors.
  • On Error: Continue (any variant) — continuing a broken run would leave the platform thinking it's still running forever, so the node terminates the run (a remote stop) before erroring, keeping the platform and the engine in sync.

The takeaway​

You don't have to hand-code failure handling around the Agent node — it already logs errors, respects your Retry setting, and makes sure a dead run doesn't linger as running. The one decision that's yours is the n8n On Error setting: Stop Workflow is the recommended default, and pairing it with Retry On Fail is the clean way to ride out transient provider blips without leaving anything half-finished.

All of the Agent node's calls back to the platform (its logs and terminates) are best-effort — if the platform is briefly unreachable, the node swallows that and continues with its primary error handling, so a platform blip never masks the real AI error.