Skip to main content

​
Overview

Pipecat Flows defines a hierarchy of exceptions for handling errors during flow execution. All exceptions inherit from FlowError, making it possible to catch all flow-related errors with a single handler. 
from pipecat_flows import (
    FlowError,
    FlowInitializationError,
    FlowTransitionError,
    InvalidFunctionError,
    ActionError,
)

​
Exception Hierarchy

FlowError
├── FlowInitializationError
├── FlowTransitionError
├── InvalidFunctionError
└── ActionError

​
FlowError

class FlowError(Exception)
Base exception for all flow-related errors. Use this for generic flow errors or as a catch-all for any flow exception. 
try:
    await flow_manager.initialize(initial_node)
except FlowError as e:
    logger.error(f"Flow error: {e}")

​
FlowInitializationError

class FlowInitializationError(FlowError)
Raised when flow manager initialization fails. Common causes include invalid configuration, missing dependencies, or calling initialize() with an invalid node config. Raised by: FlowManager.initialize()

​
FlowTransitionError

class FlowTransitionError(FlowError)
Raised when a node transition fails. This typically occurs when attempting to transition before the flow manager is initialized, or when a target node configuration is invalid. Raised by: FlowManager.set_node_from_config(), internal node transition logic

​
InvalidFunctionError

class InvalidFunctionError(FlowError)
Raised when a function cannot be registered or executed. Common causes include functions not found in the main module, invalid function signatures, direct functions that don’t return a tuple, or missing docstrings on direct functions. Raised by: Function registration, FlowsDirectFunctionWrapper.validate_function()

​
ActionError

class ActionError(FlowError)
Raised when an action execution fails. This includes both built-in actions (tts_say, end_conversation, function) and custom registered actions. Common causes include missing required fields (e.g., text for tts_say), unregistered action types, or handler execution errors. Raised by: ActionManager.execute_actions(), action handler registration