Tutorial 5: Error Handling
This chapter covers how to handle failures gracefully in workflows: on error edges make error paths explicit, and the error variable lets you access error details in fallback nodes.
Without Error Handling
First, consider a workflow that will fail — reading a nonexistent file:
[read]: read_file(file_path="/nonexistent/file.txt")
[show]: print(message="Content: " + output)
[read] -> [show]
When [read] executes, it will error (file does not exist) and the entire workflow terminates. [show] will never execute. The console output will be something like:
Error: Node [read] failed: No such file or directory
This is unacceptable in many scenarios. For example, when calling external APIs, reading user files, or running AI inference — any step can fail, but you want the workflow to keep running and follow an alternate path.
on error Basics
on error is an edge modifier. When the source node fails, instead of terminating the workflow, execution jumps to the specified fallback node.
[read]: read_file(file_path="/nonexistent/file.txt")
[fallback]: print(message="File not found, using default")
[show]: print(message="Reached the end")
[read] -> [show]
[read] on error -> [fallback]
[fallback] -> [show]
Line-by-line explanation:
[read]attempts to read the file. If successful, it follows[read] -> [show].- If it fails, the
on erroredge activates, jumping to[fallback]. [fallback]outputs an informational message, then follows[fallback] -> [show].- Whether it succeeds or fails, execution ultimately reaches
[show].
Syntax:
[source_node] on error -> [fallback_node]
Rules:
- An
on erroredge is only followed when the source node fails. Under normal conditions it is ignored. - A node can have both normal edges and
on erroredges. Normal edges are followed on success;on erroredges are followed on failure. - When a node has an
on erroredge, failure will not terminate the workflow.
Success Path vs Error Path
Use assignment syntax to mark which path was taken:
[step]: read_file(file_path="/nonexistent/file.txt")
[ok]: status = "success"
[err]: status = "failed"
[report]: print(message="Status: " + status)
[step] -> [ok]
[step] on error -> [err]
[ok] -> [report]
[err] -> [report]
At runtime, [step] will fail, so [err] executes, status is set to "failed", and the final output is:
Status: failed
If you change file_path to an existing file, [ok] executes and outputs Status: success. Two paths, one exit — this is the fundamental pattern for error handling.
The error Variable
When on error triggers, the engine automatically sets the error variable with two fields:
| Field | Type | Content |
|---|---|---|
error.node | string | The ID of the node that errored |
error.message | string | The error message |
Read it in a fallback node:
[read]: read_file(file_path="/nonexistent/file.txt")
[handle]: print(message="Error in [" + error.node + "]: " + error.message)
[read] on error -> [handle]
Output example:
Error in [read]: No such file or directory
node_id.error
In addition to the global error, each errored node’s error message is also stored in node_id.error:
[read]: read_file(file_path="/nonexistent/file.txt")
[handle]: print(message="read node error: " + read.error)
[read] on error -> [handle]
error is global and always points to the most recently errored node. node_id.error is node-specific and more precise in multi-node error handling scenarios.
Multi-Level Error Handling
Different nodes can have different fallbacks:
[load_config]: read_file(file_path="/etc/app/config.json")
[load_data]: read_file(file_path="/tmp/data.csv")
[process]: print(message="Processing data...")
[config_fallback]: config = "default"
[data_fallback]: data = "empty"
[done]: print(message="Workflow complete")
[load_config] -> [load_data]
[load_config] on error -> [config_fallback]
[config_fallback] -> [load_data]
[load_data] -> [process]
[load_data] on error -> [data_fallback]
[data_fallback] -> [process]
[process] -> [done]
Execution flow:
[load_config]attempts to read the configuration. If it fails, it jumps to[config_fallback], sets a default value, then continues to[load_data].[load_data]attempts to read data. If it fails, it jumps to[data_fallback], sets empty data, then continues to[process].- Regardless of which step fails, the workflow can always reach
[done].
Each “potentially failing” node has its own fallback, without interfering with others.
Error Handling + Conditional Branching
on error can be combined with conditional edges:
[init]: mode = "strict"
[work]: read_file(file_path="/tmp/important.txt")
[ok]: print(message="File loaded")
[warn]: print(message="File missing, but mode is lenient")
[abort]: print(message="File missing in strict mode, aborting")
[done]: print(message="Done")
[init] -> [work]
[work] -> [ok]
[work] on error -> [warn]
[work] on error -> [abort]
[ok] -> [done]
[warn] -> [done]
[abort] -> [done]
Here, two on error edges are defined for the same node. When [work] fails, both on error edges fire — [warn] and [abort] will both run. If you want to choose between strategies, route to a single error-handler node and branch from there (see the next section).
If you need to differentiate error handling strategies based on context, a better approach is to have the fallback node handle the decision internally:
[init]: mode = "strict"
[work]: read_file(file_path="/tmp/important.txt")
[ok]: print(message="File loaded")
[error_router]: print(message="Handling error...")
[warn]: print(message="File missing, lenient mode")
[abort]: print(message="Strict mode, abort!")
[done]: print(message="Done")
[init] -> [work]
[work] -> [ok]
[work] on error -> [error_router]
[error_router] if mode == "strict" -> [abort]
[error_router] -> [warn]
[ok] -> [done]
[warn] -> [done]
[abort] -> [done]
on error jumps to [error_router], which then uses conditional branching based on mode — error handling and routing logic each have their own responsibility.
Comprehensive Example
A complete workflow with a normal path and multiple error handlers:
[start]: errors = 0
# Step 1: Load configuration
[load_config]: read_file(file_path="/etc/app/config.json")
[config_ok]: config_loaded = true
[config_err]: config_loaded = false, errors = errors + 1
# Step 2: Load data
[load_data]: read_file(file_path="/tmp/dataset.csv")
[data_ok]: data_loaded = true
[data_err]: data_loaded = false, errors = errors + 1
# Step 3: Summary
[report]: print(
message="Pipeline done. Errors: " + str(errors)
)
# Normal path
[start] -> [load_config]
[load_config] -> [config_ok]
[config_ok] -> [load_data]
# Config load failure
[load_config] on error -> [config_err]
[config_err] -> [load_data]
# Data load
[load_data] -> [data_ok]
[data_ok] -> [report]
# Data load failure
[load_data] on error -> [data_err]
[data_err] -> [report]
This workflow demonstrates a common “best effort” pattern:
- Each potentially failing step has an
on erroredge. - Fallback nodes record the error (incrementing a counter), then let the workflow continue.
- The final
[report]node summarizes the error count. - Regardless of which intermediate step fails, the workflow always reaches the end.
Summary
[node] on error -> [fallback]– When a node errors, jump to the fallback instead of terminating the workflowerror.nodeanderror.message– Global error variables containing the most recent error’s node ID and error messagenode_id.error– Node-level error message, suitable for multi-node error handling- Each potentially failing node can have its own independent fallback
on errorcan be combined with conditional edges and switch routing- Common pattern: fallback nodes set default values or record errors, then rejoin the normal flow
Next chapter: Tutorial 6: AI Chat – Learn how to call AI models in workflows, construct multi-turn conversations, and obtain structured output.