Error Flow

TL;DR: Error flows catch failures anywhere in your bot (nodes, agents, etc.) and provide a controlled recovery path. Maximum one per bot. When triggered, the conversation locks into the error flow — users can't escape and transitions are blocked. Keep them simple and use the _error_flow_reason slot to access error details.

An Error Flow is a special type of flow designed to handle unexpected failures that occur during bot conversations. When any component of your bot encounters an error, the error flow is automatically triggered, allowing you to provide a graceful shutdown path instead of leaving users with a broken conversation.

Why Use Error Flows?

Error flows give you control over what happens when something goes wrong in your bot. Instead of crashing the conversation, you can:

• Display user-friendly error messages
• Apologize and explain what happened
• Offer alternative actions or workarounds
• Escalate to a human agent via live chat
• Log the error details for debugging

Creating an Error Flow

To create an error flow:

1. Navigate to the Content section and click Create to start a new flow.
2. Give your flow a descriptive name (e.g., "Error Flow" or "Failure Recovery") and a short description.
3. Check the Error Flow checkbox.

Note: When you enable the Error Flow option, several settings are automatically configured:

• The flow becomes a Subflow Only (it won't be selected by the orchestrator)
• Default Flow cannot be enabled (a flow cannot be both default and error flow)

Editing an Existing Flow to Be an Error Flow

You can also convert an existing flow into an error flow:

1. Open the flow you want to convert.
2. Click the Edit icon to open the flow settings.
3. Check the Error Flow checkbox.
4. Save your changes.

Important: You can have at most one error flow per bot. If you enable error flow on a different flow, the previous error flow will automatically be converted back to a regular subflow.

When Is the Error Flow Triggered?

The error flow is automatically triggered when any node or component in your bot encounters an error. This includes:

Story Nodes

• LLM Response Node - Failures in generating responses
• Action Node - Runtime errors in your custom Python scripts
• Branch Node - Errors evaluating conditions or rules
• Form Node - Failures in form validation or data extraction
• RAG Node - Issues retrieving or processing knowledge
• Flow Transition Node - Errors during flow transitions
• Any other node type - Any unexpected failure during execution

Bot Components

• Orchestrator Agent - Failure to select an appropriate flow
• Guard Agent - Security or validation failures
• Pre-processing Agent - Errors during input preprocessing
• Post-processing Agent - Errors during response postprocessing

General Errors

• Rate Limiting - When rate limits are exceeded
• Any component raising a Flow Aborted Event

When any error occurs in any part of the conversation pipeline, the system automatically converts the error into a FlowExecutionErrorEvent and activates your error flow.

Error Flow Behavior

Conversation Locking

When the error flow is triggered, the conversation is locked into the error flow. This means:

• Users cannot escape the error flow by typing messages
• The orchestrator will not redirect to other flows
• Flow transition nodes will not work and will raise an error
• Custom actions cannot force a transition to another flow
• The only transitions that do work are into the bot hang up and user hang up flows

This ensures your error handling logic handels any additional user input as the conversation might be in a broken state.

Blocked Transitions

While the error flow is active, the following transition mechanisms are blocked and will raise a runtime error:

• Flow Transition Nodes - Cannot transition to another flow
• Forced Transitions - Custom actions cannot force flow changes
• Orchestrator Events - Orchestrator cannot override the active error flow

Warning: If you attempt to use a Flow Transition node or force a transition via custom action while the error flow is active, the system will raise a RuntimeError with a message like:

"Attempted to transition to flow 'FlowName' while the error flow 'YourErrorFlow' is locked."

Error Information

The system automatically stores information about the error in a special slot called _error_flow_reason. This slot is only accessible from inside the error flow. You can use this slot to:

• Display the error details to users
• Log the error for debugging
• Make decisions based on the error type

Example: In an LLM Response node, you could write:

I apologize, but I encountered an error: {{_error_flow_reason}}

Let me help you get back on track.

Disabled Features Inside Error Flows

To prevent the error flow itself from crashing, certain features are automatically disabled:

• Pre-processing Agent - Skipped during error flow execution
• Post-processing Agent - Skipped during error flow execution

This helps ensure your error handling is as stable as possible.

What Happens If the Error Flow Itself Fails?

If an error occurs within the error flow itself, the system will raise a FlowAbortedEvent (not a FlowExecutionErrorEvent). This prevents an infinite loop of error flows triggering themselves.

In this case, the conversation will abort and the user will need to restart.

Best Practice: Keep your error flows simple and robust. Avoid complex logic or external dependencies that might fail.

Technical Overview

Here's a high-level overview of how error flows work behind the scenes:

1. Error Detection: When any component raises a FlowAbortedEvent, the system checks if an error flow is configured.

2. Event Conversion: If an error flow exists and the bot is not already in the error flow, the FlowAbortedEvent is converted to a FlowExecutionErrorEvent.

3. Error Flow Activation: The error flow is activated, replacing any currently running flow.

4. Error Reason Storage: The error reason from the event payload is stored in the _error_flow_reason slot.

5. Conversation Lock: The conversation is locked to prevent escaping the error flow.

6. Agent Deactivation: Pre-processing and post-processing agents are deactivated to prevent further errors.

7. Flow Execution: The error flow runs to completion, allowing you to handle the error gracefully.

Important Restrictions

Keep these restrictions in mind when working with error flows:

Restriction	Description
One per bot	You can have at most one error flow per bot
Must be a subflow	Error flows are always subflows and cannot be selected by the orchestrator
Not parallelizable	Error flows always run sequentially
Cannot be default	A flow cannot be both an error flow and a default flow
No transitions out	While active, you cannot transition to other flows (except the hang up flows)
No nested errors	Errors within the error flow raise FlowAbortedEvent

Best Practices

1. Keep It Simple

Design your error flow to be as simple as possible. Avoid complex logic, external API calls, or anything that might fail. The goal is reliability.

Good example:

- LLM Response: "I apologize, I encountered a technical issue. Please try again or contact support."
- Provide options to restart or speak with an agent

Avoid:

- Multiple complex RAG queries
- Chained API calls
- Complicated branching logic

2. Use the Error Reason Slot

Make use of the _error_flow_reason slot to provide context about what went wrong. You can reference it in your responses or use it for logging.

3. Provide Clear Next Steps

Always give users a clear path forward:

• Offer to restart the conversation
• Provide contact information for support
• Suggest alternative ways to accomplish their goal
• Transfer to a human agent if available
• Offer to create a support ticket

4. Test Your Error Flow

Intentionally trigger errors to test your error flow:

• Create a custom action that raises an exception
• Test with invalid data
• Verify the error messages are user-friendly

5. Log for Debugging

Use action nodes to log error details for later analysis. This helps you improve your bot over time.

Example:

# In a custom action
slot_value = tracker.get_slot("_error_flow_reason")
logger.error(f"Error flow triggered: {slot_value}")

Related Documentation

• Flow - Learn about creating and managing flows
• Scripts - Create custom actions for error handling
• Knowledge - Configure RAG agents that might trigger errors