Error Handling

Governance decisions surface as NodeOperationError thrown from the OpenBox: Agent node's execute() function. Internally, the node maps three governance exception types to that error.

Governance Exceptions

Exception	Raised when	Node error message
`GovernanceHaltError`	Policy verdict is `HALT`, or a required approval is rejected or times out	The exception's own message
`GovernanceBlockedError`	Policy verdict is `BLOCK`	`OpenBox governance requires approval` (with the underlying reason attached as the error description)
`GuardrailsValidationError`	A configured guardrail rejects the input or output	`OpenBox guardrails validation failed: <reasons>`

All three surface as a single NodeOperationError on the node — n8n does not expose separate error classes to catch inside the workflow. Route on the error instead using Continue On Fail or an IF/Error Trigger node downstream.

Continue On Fail

By default, a governance error fails the whole node execution. Enable Continue On Fail (Settings icon on the node → On Error → Continue) to route errors as an output item instead:

{ "error": "OpenBox governance requires approval" }

This lets you branch on {{$json.error}} with an IF node rather than stopping the workflow.

Non-Governance Tool Errors

If a connected Tool sub-node throws (for example an HTTP 4xx/5xx from a Tool HTTP Request node), the agent stops immediately and returns:

Tool "<tool name>" failed: <error message>

This is treated as the agent's final output, not a governance error — it does not raise GovernanceHaltError, GovernanceBlockedError, or GuardrailsValidationError. WorkflowCompleted still fires with a failed status so the run is recorded in OpenBox.

Approval Rejection And Timeout

If OpenBox returns REQUIRE_APPROVAL, the node polls for a decision. If the reviewer rejects the request, or no decision arrives before the timeout, the node raises GovernanceHaltError — there is no separate rejected/expired exception type in the n8n node.

Best Practices

Enable Continue On Fail for governed nodes in production — treat a block or halt as an expected outcome, not a crash.
Branch on the error message, not exception identity — n8n surfaces one error type (NodeOperationError) regardless of the underlying governance reason.
Log the error message — it contains the policy or guardrail reason from OpenBox.
Don't retry blindly on a block — a BLOCK verdict is a policy decision, not a transient failure.

Debugging

Check the execution in n8n's Executions tab, then open the OpenBox: Agent node's output to see the error and, on success runs, the _openbox metadata block (workflow ID, run ID, tool call count, iterations). Cross-reference the workflow/run ID in the OpenBox Dashboard to see the full event timeline and the policy or guardrail message.

Next Steps

Configuration — Review credential and node parameter defaults
Integration Walkthrough — Wire and verify an existing n8n agent
Approvals and Guardrails — Understand verdict and guardrail behavior
Troubleshooting — Diagnose common integration issues

Governance Exceptions​

Continue On Fail​

Non-Governance Tool Errors​

Approval Rejection And Timeout​

Best Practices​

Debugging​

Next Steps​