Catch
Catches and handles errors that occur in flows.
Where and why do we use the Catch node?
The Catch node handles errors within your flows, preventing crashes and enabling graceful error recovery. When an error occurs in any node, the Catch node intercepts it and lets you respond appropriately - whether that's logging the error, retrying the operation, sending alerts, or providing user feedback. This is essential for building robust flows that can handle unexpected situations without failing completely.
Note: Some third-party nodes have their own error-handling mechanisms, such as updating status or sending custom error messages, which may not properly inform the runtime about errors occurring. The Catch node cannot capture or handle these errors.
Modes of operation
The Catch node can be configured to catch errors from different scopes:
All Nodes
Captures errors from all nodes in the same tab or flow. This is useful for implementing flow-wide error handling where you want a single catch-all error handler.
Same Group
Limits error capture to nodes within the same group as the Catch node. Use this when you want isolated error handling for specific sections of your flow that are grouped together.
Selected Nodes
Captures errors from specific nodes you choose. This gives you fine-grained control over which nodes' errors are handled by this particular Catch node, useful when different nodes need different error handling strategies.
How the node handles messages
When an error occurs in a monitored node, the Catch node emits a message object containing error information. The node doesn't modify or stop the original error - it creates a new message flow that you can use to respond to the error.
The message object emitted by the Catch node contains:
- payload - the payload that was passed to the node which threw the error
- error.message - the error message text
- error.source - object containing information about the node that logged the error:
- id - the source node id
- type - the type of the source node
- name - the name, if set, of the source node
- count - how many times this message has been thrown by this node
This information lets you implement sophisticated error handling logic, including conditional responses based on which node failed or what type of error occurred.
Examples
Error handling for external integrations
The Catch node handles errors when interacting with APIs, including network issues, response errors, server unavailability, database connection losses, timeout errors, and MQTT broker disconnections. It can also trigger retry actions as necessary.
In this example, the inject node sets a request timeout of 2000 milliseconds. The HTTP request node calls a mock URL with a 3-second delay parameter, simulating a delayed response. This causes a timeout error that the Catch node intercepts. After catching the error, the flow retries the request after a 5-second delay.
User input validation
In applications with user input, validation errors can disrupt the flow. The Catch node handles these errors, providing feedback or corrective actions to guide users.
In this example, the function node attempts to sort input data received from an inject node using the sort method, which only works with arrays. Sending other data types causes an error that the Catch node catches, which then sends a validation message to the user.
Node Documentation
Catch errors thrown by nodes on the same tab.
Outputs
Details
If a node throws an error whilst handling a message, the flow will typically halt. This node can be used to catch those errors and handle them with a dedicated flow.
By default, the node will catch errors thrown by any node on the same tab. Alternatively it can be targetted at specific nodes, or configured to only catch errors that have not already been caught by a 'targeted' catch node.
When an error is thrown, all matching catch nodes will receive the message.
If an error is thrown within a subflow, the error will get handled by any catch nodes within the subflow. If none exists, the error will be propagated up to the tab the subflow instance is on.
If the message already has a error property, it is copied to _error.