- Get started
- Build
- Deploy and run
- Examples
- Reference
Handle errors
Route failed nodes to an error path, log the error details, retry temporary failures, and end the workflow cleanly on unrecoverable errors.
What you build
A workflow that routes a failing node to a separate path, logs the failure with useful context, retries temporary failures where that makes sense, and ends cleanly when the error is unrecoverable. The result is a pattern that fits into any existing workflow.
Before you start
- An existing workflow with at least one node that can fail and has an Error handling tab, for example an HTTP Request or an Extract node.
Nodes used
- HTTP Request: the node that can fail in this example.
- Script: logs the error details.
- Terminate: ends the workflow on unrecoverable errors.
Steps
With a coding agent set up, you can skip the manual steps. Ask it:
Add error handling to the HTTP Request node in this Maestro Automate workflow: connect its error path to a Script node that logs the error message, retry temporary failures, and end the run with a Terminate node when the error can't be recovered.
Add error handling to the HTTP Request node in this Maestro Automate workflow: connect its error path to a Script node that logs the error message, retry temporary failures, and end the run with a Terminate node when the error can't be recovered.
Then open the workflow on the canvas, check it against the steps below, and test it. Set up your coding agent describes the setup.
1. Connect the node's error handle
By default, a failed node stops the entire workflow. To handle the failure instead:
- Open the workflow on the canvas and select the node that can fail.
- Open the Error handling tab and turn on Enable error handling. An Error handle appears below the main output handle.
- Select the + on the Error handle, search for Script, and select it.
This creates an error path. When the node fails, the run follows this path instead of stopping the workflow. A node without an Error handle does not support error handling, and a failure there stops the workflow and appears in the Incidents tab.
2. Log the error
In the Script node on the error path, read the error object at $vars.<node>.error:
const error = $vars.httpRequest1.error;
console.log('Step failed:', error.message);
console.log('Code:', error.code, '| HTTP status:', error.status);
return { logged: true };
const error = $vars.httpRequest1.error;
console.log('Step failed:', error.message);
console.log('Code:', error.code, '| HTTP status:', error.status);
return { logged: true };
The error object is only populated on the error path. The Error handling page lists the full set of error fields.
3. Retry transient failures (optional)
If the failure is likely to be temporary, such as a network interruption or a rate limit, retrying before giving up helps. The HTTP Request node has built-in retries: setting Retry count on its Advanced tab makes it re-attempt the request that many times before triggering the error handle. Only the final failure routes to the error path.
Retry only operations that can safely run more than once. Retrying a node with side effects, such as writing data or sending a message, can create duplicates.
4. Terminate if unrecoverable
On the error path, after the Script node, add a Terminate node. To return the failure description, select Add output variable on the node and give it a value that includes the error, for example $vars.httpRequest1.error.message.
The workflow ends at the Terminate node, and the run is listed in Monitor runs.
5. Test and debug
To trigger the error path intentionally:
- Temporarily set the URL in the HTTP Request node to an invalid value (for example,
https://this-will-fail.example.com). - Select Run Debug (▶) in the bottom toolbar of the canvas and verify that the execution trace follows the error path.
- Restore the correct URL.
Check the Script node's console output in the trace to confirm the error details are logged.
Result
The workflow routes failures to the error path, logs the error details, optionally retries temporary failures, and ends cleanly with a descriptive failure status. An invalid URL in the HTTP Request node confirms that the error path works.
Extend this workflow
- Send an alert on failure: on the error path, before the Terminate node, add an HTTP Request or connector node to notify a Slack channel or create a ServiceNow incident.
- Continue instead of terminating: if the step is non-critical, have the error path set a fallback value and rejoin the main path instead of terminating.
- Apply this pattern widely: the Error handling page describes more patterns, such as log and continue, fallback values, and escalation.
Next steps
- Deploy a workflow: make the workflow run without you.
- Guides: more workflows to build.
- Community: share what you built, or ask other builders for help.