- Get started
- Build
- Deploy and run
- Examples
- Reference
Error handling
How a node failure can be routed to a separate path through the node's error handle, and how the error details are exposed through variables.
Error handling is a per-node mechanism that controls what happens when a node fails during a run. By default, a failed node stops the entire workflow. Connecting the node's error handle routes the failure to a separate path, where the workflow can inspect and respond to the error.
How it works
Every node that supports error handling has an Error handling tab in its properties panel. The Enable error handling toggle on that tab adds an error output handle to the node, a second output connector labeled Error, below the main output handle on the right side of the node, that activates when the node fails. Most nodes support error handling.
When a node with a connected error handle fails, the run follows the error path instead of stopping the workflow. The error details become available as a variable that later nodes can read.
When a node without a connected error handle fails, the run stops at that node. In a test run, the error appears on the Incidents tab below the canvas. In a deployed run, the run pauses until you retry or cancel it, as Retry and cancel describes.
HTTP Request retries
The HTTP Request node supports configurable retries. When retries are configured, the node attempts the request the specified number of times before triggering the error handle. If all retries fail and an error handle is connected, the run follows the error path. If no error handle is connected, the workflow fails.
Configuring error handles
Turning on Enable error handling in the Error handling tab of the properties panel adds the error handle to the node. Connecting the Error handle to another node on the canvas wires the error path. A node without an Error handle does not support error handling, so any failure stops the workflow.
The error object
When an error handle is connected and the node fails, the error details are available as $vars.<nodeName>.error. The object has these fields:
code: a machine-readable code that identifies the type of failure.message: a human-readable description of what went wrong, suited to logging or showing to a user.detail: a technical description of the failure, including stack traces (the list of calls that led to the failure) or service-specific information when available.category: the error category, which groups related error types.status: the HTTP status code that belongs to the error, for example404or500. It is filled in for HTTP-related failures.
The error object is only available on the error path. Accessing $vars.<nodeName>.error on the success path returns undefined.
Practical example
This example uses an HTTP Request node to call an external API, with a Script node on the error path that logs the failure. The HTTP Request node is configured with the target URL. Its error handle is connected to a Script node. The Script node reads the error object as follows:
const error = $vars.httpRequest1.error;
return {
failed: true,
reason: error.message,
httpStatus: error.status,
detail: error.detail
};
const error = $vars.httpRequest1.error;
return {
failed: true,
reason: error.message,
httpStatus: error.status,
detail: error.detail
};
When the HTTP request succeeds, the run follows the success path and the Script node is skipped. When the request fails, after any configured retries, the run follows the error path to the Script node, which receives the full error object.
On a successful run, the success path runs and the error path is skipped:
On a failed run, the error path runs instead:
Patterns
These are common approaches to handling, logging, retrying, and escalating errors. They all build on the per-node error handle described above: a connected error handle routes failures to a separate path, where the error object is available at $vars.<node>.error.
Log and continue
This pattern fits non-critical operations where the workflow should continue even if one step fails. The node's error handle connects to a Script node that logs the error, then rejoins the main path so the run continues.
// Script node on the error path
console.log('Non-critical step failed:', $vars.step1.error.message);
return null; // downstream nodes handle null gracefully
// Script node on the error path
console.log('Non-critical step failed:', $vars.step1.error.message);
return null; // downstream nodes handle null gracefully
Retry with limit
This pattern fits failures that are likely to be temporary, such as network timeouts, rate limits, or service outages. For the HTTP Request node, the built-in retry count re-attempts the request before triggering the error handle, and only the final failure routes to the error path. Retry settings belong only on idempotent operations.
Alert and terminate
This pattern fits unrecoverable errors that require human attention. On the error path, a notification is sent through an HTTP Request or integration node, then a Terminate node ends the workflow, with an output variable that holds a descriptive message such as $vars.step1.error.message.
Fallback value
This pattern fits operations that may fail but have a safe default value that allows the workflow to continue meaningfully. On the error path, a Script node sets the expected output to a default value, then rejoins the main path as if the operation had succeeded.
Common mistakes
- Swallowing errors silently: errors on the error path should always be logged, even when the workflow continues. Silent failures are hard to diagnose later.
- Retrying operations that cannot safely repeat: operations with side effects, such as writing data or sending a message, may produce duplicates if retried. Retry settings belong only on operations that can run more than once without creating duplicates.
- Leaving error handles unconnected: a node whose error handle is not connected fails the entire workflow on error. A workflow that should continue past a failure needs a connected error path.
Next steps
- Handle errors: a step-by-step task that builds an error path.
- The Flow canvas: the workspace, including the panel below the canvas.
- Variables and data flow: how data passes between nodes with
$vars. - Debugging basics: tips for inspecting errors during a debug run.
- Community: ask questions and share workflows with other builders on the UiPath Forum.