Skip to main content
Error handling allows you to control how an agentic workflow responds when a node fails. Instead of stopping execution, you define how the agentic workflow flow reacts. You can retry the node, show a message to the user, or redirect execution to another path. This approach helps you design agentic workflows that handle failure explicitly and predictably. You configure error handling per node by using the NodeErrorHandlerConfig class. You can attach this configuration to both tool nodes and agent nodes. NodeErrorHandlerConfig defines how a node behaves when an execution error occurs. It controls retry behavior, error messaging, and redirection within the agentic workflow flow. When you attach this configuration to a node, you allow the flow engine to evaluate errors at runtime and decide how execution continues. To configure error handling, create a NodeErrorHandlerConfig instance and pass it to a node when you call tool() or agent() in your agentic workflow.
Python
aflow.tool(
    "someTool",
    error_handler_config=NodeErrorHandlerConfig(
        on_error="branch",
        error_edge_id="some_error_edge"
    )
)
Parameters:
​
error_message
required
Describes the error that occurred.The flow engine logs this message for observability and debugging.The agentic workflow flow does not display this message to the user unless you explicitly expose it through a user flow or UI element.
​
max_retries
required
Specifies how many retry attempts occur after a failure.If you set this value to 0, the node follows the configured error behavior immediately.If you omit this value, the platform default retry behavior applies.
​
retry_interval
required
Defines the delay between retries in milliseconds.This setting applies only when max_retries is greater than 0.
​
on_error
required
Defines how the agentic workflow flow responds when the node fails.Supported values:
  • show_message: Stops the agentic workflow after displaying an error message to the user. Use this option when no alternate path applies.
  • branch: Redirects the agentic workflow flow to an alternate path using the edge specified by error_edge_id. Use this option to handle expected failures, guide users to a recovery path, or invoke fallback logic when tools or external services return errors. This option suits agentic workflows that rely on services with variable availability.
​
error_edge_id
required
Specifies the edge that execution follows when on_error="branch" is set.This value must match an edge defined with aflow.edge(...).If no matching edge exists, the agentic workflow fails during validation or execution.
The following example shows an agentic workflow that retrieves dog facts. When the tool fails, the agentic workflow flow redirects execution to a user flow that displays an error message.
Python [Expandable]
"""
Error Branching Example Flow
"""

from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import (
    Flow, flow, START, END
)
from ibm_watsonx_orchestrate.flow_builder.types import (
    UserFieldKind,
    NodeErrorHandlerConfig
)

class PetFacts(BaseModel):
    facts: list[str] = Field(description="A list of facts about the pet")

@flow(
    name="get_pet_facts_error_branching",
    output_schema=PetFacts,
    description="Shows a user message when fetching dog facts fails"
)
def build_get_pet_facts_error_branching_flow(aflow: Flow) -> Flow:

    # User flow that displays an error message
    user_flow = aflow.userflow()

    error_message_node = user_flow.field(
        direction="output",
        name="error_display",
        display_name="Error Message",
        kind=UserFieldKind.Text,
        text="Sorry, we couldn't fetch dog facts at this time. Please try again later."
    )

    user_flow.edge(START, error_message_node)
    user_flow.edge(error_message_node, END)

    # Tool node with error handling
    dog_fact_node = aflow.tool(
        "getDogFact",
        error_handler_config=NodeErrorHandlerConfig(
            error_message="Dog facts retrieval failed; redirecting to user message",
            max_retries=0,
            retry_interval=1000,
            on_error="branch",
            error_edge_id="dog_error_to_user_message"
        )
    )

    # Main execution path
    aflow.sequence(START, dog_fact_node, END)

    # Error branching path
    aflow.edge(dog_fact_node, user_flow, id="dog_error_to_user_message")
    aflow.edge(user_flow, END)

    return aflow