Catch
# What is the Catch Node?
The Catch node in Node-RED is crucial for handling errors within your flows. Whenever an error occurs within the flow, this node catches it. Once the Catch node catches an exception, it can pass relevant information in the msg object to another node.
This helps you manage and respond to errors that may occur during flow execution and also prevent crash, which ensures smooth operation and effective error management.
Note: Some third-party nodes have their own error-handling mechanisms, such as updating status or sending custom error messages which does properly inform to runtime about error ocurring. The catch node is unable to capture or handle these errors.
# Configuring the Catch Node
The catch node can be configured with "Catch errors from" property with following options:
-
All Nodes: Captures errors from all nodes in the same tab or flow.
-
In same Group: Limits error capture to nodes within the same group of which it is part of.
-
Selected Nodes: Captures errors from specific nodes chosen by you.
# Use Cases and 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. Additionally, it performs retry actions as necessary. .
In the example flow below, the inject node sets a request timeout of 2000 milliseconds. In the HTTP request node, we have passed a mock URL with the delay parameter set to 3 seconds, simulating a delayed response. This simulated delay will cause a request timeout error, which will then be caught by the Catch node. After catching the error, the flow will retry the request after a delay of 5 seconds.
- 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.
In the example flow below, the function sorts input data received from an inject node using the sort method, which is only available for arrays. Sending other data types will cause error and that will get caught by the catch node, which then sends an validation message.
# Message object emmited by Catch node
The Catch node emits a message object when an error occurs, containing the following properties:
- payload : the payload which is passed to node which has thrown error.
- message : the error message
- source - object containing information about the node logging 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.
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.