Exceptions

Error handling hierarchy for Pipecat Flows

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