Exceptions

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 initialize() fails, such as when the initial node config is invalid. 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 handler is invalid: a direct function with a bad signature or no docstring, a handler that returns something other than a result or a (result, next_node) tuple, or a tool on a node built in Python that returns TRANSITION_IN_YAML. Raised by: Function registration, FlowsDirectFunctionWrapper.validate_function(), and the handler that runs a function call

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}")

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.

str

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

str

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

str | None

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

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.

Get Started

Standards

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub