Error Handling & Retry on Error
Relevant source files
The following files were used as context for generating this wiki page:
- packages/core/src/execution-engine/workflow-execute.ts
- packages/workflow/src/errors/node-operation.error.ts
- packages/nodes-base/nodes/StopAndError/StopAndError.node.ts
- packages/nodes-base/nodes/ErrorTrigger/ErrorTrigger.node.ts
- packages/workflow/src/errors/node-api.error.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/enrichment.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/monitoring.ts
- packages/nodes-base/nodes/Microsoft/AzureCosmosDb/test/helpers/errorHandler.test.ts
Error handling is a critical aspect of creating robust and reliable workflows in n8n. The platform provides a multi-layered approach to detect, manage, and respond to errors that may occur during workflow execution. This includes node-level settings for transient failures, dedicated nodes for explicit error management, and a global system for catching unhandled exceptions.
The core components of this system are node settings like "Continue on Fail" and "Retry on Fail", specialized nodes such as Stop and Error and Error Trigger, and distinct error classes like NodeOperationError and NodeApiError. Together, these features allow developers to build resilient automations that can gracefully handle unexpected issues, from API outages to data validation failures.
Core Error Handling Concepts
Node-Level Error Settings
Nodes can be configured with specific behaviors to manage failures during their execution.
-
Continue on Fail: A crucial setting for building resilient workflows. When enabled on a node, the workflow will not stop if that node fails. Instead, the error information is passed to the next nodes, typically to an error-handling branch. This is essential for monitoring workflows, where a check failure should trigger an alert, not crash the workflow.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/monitoring.ts:11, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/enrichment.ts:31 -
Retry on Fail: This setting allows a node to automatically retry its execution a configured number of times if it fails. It is particularly useful for handling transient issues like temporary network problems or API rate limiting. An interval can be set between retries.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/monitoring.ts:31, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/enrichment.ts:133
Error Outputs
Some nodes feature a dedicated error output, which is the last output connector. The execution engine can route failed items to this output. The handleNodeErrorOutput function in the workflow executor checks if an item contains an error property in its JSON data. If it does, and the node has a dedicated error output, the item is moved from the main output to the error output. This allows for creating specific logic branches to handle items that failed within a node.
Sources: packages/core/src/execution-engine/workflow-execute.ts:2018-2092
The following diagram illustrates the logic for routing items to an error output.
Error Handling Nodes
n8n provides specialized nodes for explicitly managing and triggering error states.
Stop and Error Node
The StopAndError node is used to deliberately halt a workflow's execution and mark it as failed. This is useful for validating data and stopping the process if conditions are not met. It generates a NodeOperationError with a custom message.
| Parameter | Type | Description |
|---|---|---|
message | string | The custom error message to display. Can contain expressions. |
alwaysOutputData | boolean | If enabled, the node will output the error data, allowing it to be caught by an Error Trigger workflow. |
Sources: packages/nodes-base/nodes/StopAndError/StopAndError.node.ts:25-78
This is how it is implemented in the execute method:
// packages/nodes-base/nodes/StopAndError/StopAndError.node.ts:59-69
async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
const alwaysOutputData = this.getNodeParameter('alwaysOutputData', 0, false) as boolean;
const message = this.getNodeParameter('message', 0, '') as string;
if (alwaysOutputData) {
const item = this.getInputData();
const error = new NodeOperationError(this.getNode(), message);
item[0].json.error = error;
return this.prepareOutputData(item);
}
throw new NodeOperationError(this.getNode(), message);
}
Sources: packages/nodes-base/nodes/StopAndError/StopAndError.node.ts:59-69
Error Trigger Node
The ErrorTrigger node is a unique trigger that starts a workflow when another workflow in the same n8n instance fails. This enables the creation of a centralized, global error-handling workflow.
Key features:
- It can be configured to trigger for all failed workflows or only for specific ones.
- It receives data about the failed execution, including the error message, workflow ID, and execution details.
- The workflow containing the
ErrorTriggermust be activated and designated as the "Error Workflow" in the instance settings.
This diagram shows the sequence of events when a global error workflow is triggered.
Error Classes
n8n uses specific error classes to differentiate between types of failures.
| Error Class | File Path | Description |
|---|---|---|
NodeOperationError | packages/workflow/src/errors/node-operation.error.ts | Represents an error caused by a node's operation, often due to invalid user input or configuration. This is a user-facing error. |
NodeApiError | packages/workflow/src/errors/node-api.error.ts | Represents an error returned from an external API call. It typically wraps the HTTP response and status code from the API. |
Sources: packages/workflow/src/errors/node-operation.error.ts, packages/workflow/src/errors/node-api.error.ts
The NodeApiError is particularly useful for providing detailed context about API failures. It can be constructed with a custom message and description, which can be extracted from the API response body.
Sources: packages/nodes-base/nodes/Microsoft/AzureCosmosDb/test/helpers/errorHandler.test.ts:21-30
Execution Engine Error Handling
The WorkflowExecute class is central to how errors are managed during a run.
Error Handling in runNode
When a node is executed via the runNode method, its execution is wrapped in a try...catch block. If an exception is thrown:
- The engine checks if the error is a
NodeOperationErrororNodeApiError. - If it is, it sends an
errorchunk via thesendChunkhook, which can be used for real-time feedback in the UI. The chunk contains the error description and metadata about the node and item. - The error is then re-thrown to be handled by the main execution loop.
Sources: packages/core/src/execution-engine/workflow-execute.test.ts:2416-2443, packages/core/src/execution-engine/workflow-execute.ts
Final Execution State
The processSuccessExecution method is called at the end of a workflow run. It determines the final status of the execution. If an error was passed to it, the execution is marked as failed, and the error object is attached to the final run data. This ensures that even if a workflow is configured to "continue on fail," the overarching execution is still recorded as having encountered an error.
Sources: packages/core/src/execution-engine/workflow-execute.ts:1820-1829
Summary
n8n's error handling framework provides a comprehensive toolkit for building resilient workflows. By combining node-level settings like "Retry on Fail" for transient issues, explicit error management with the Stop and Error node, and global oversight with the Error Trigger node, developers can anticipate and manage a wide range of potential failures. Understanding the different error classes and how the execution engine processes them is key to leveraging these features effectively and creating automations that are both powerful and reliable.