Exceptions

The Pipecat Flows exception hierarchy: FlowError and subclasses raised during flow execution, and how to handle each.

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,
    FlowProblem,
    FlowReferenceError,
    FlowTransitionError,
    InvalidFunctionError,
    ActionError,
)

Exception Hierarchy

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

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

FlowReferenceError

class FlowReferenceError(FlowError)

Raised when a flow config’s references cannot all be resolved. Constructing a Flow checks every tool and action handler the config names and raises this once, with every unresolved reference, rather than stopping at the first.

Raised by: Flow.__init__()

from pipecat.flows import Flow, FlowConfig, FlowReferenceError

try:
    flow = Flow(FlowConfig.from_file("flow.yaml"), handlers=handlers)
except FlowReferenceError as e:
    for problem in e.problems:
        logger.error(f"{problem.code}: {problem.message}")

problems · list[FlowProblem]

Every unresolved reference, in the order found. Also rendered into the exception’s message, one per line.

FlowProblem

@dataclass
class FlowProblem

One reference a flow config makes that its handlers do not satisfy. Not an exception itself — a FlowReferenceError carries a list of them.

code · str

Stable identifier for the kind of problem. See the table below.

message · str

Human-readable description naming the node, function, or handler involved.

node · str | None

The node the problem is about, when there is one. None for a problem in global_functions.

function · str | None

The function entry the problem is about, when there is one.

Codes

Code	Meaning
missing_tool	A tool the config names is not in the handlers.
ambiguous_tool	A tool name resolves to different callables in more than one of the handlers.
invalid_tool	A tool is not callable, or is not a valid direct function.
missing_handler	An action handler the config names is not in the handlers, or is not callable.
ambiguous_handler	An action handler name resolves to different callables in more than one of the handlers.