> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-flows-declarative.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```python theme={null}
from pipecat.flows import (
    FlowError,
    FlowInitializationError,
    FlowProblem,
    FlowReferenceError,
    FlowTransitionError,
    InvalidFunctionError,
    ActionError,
)
```

## Exception Hierarchy

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

## FlowError

```python theme={null}
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.

```python theme={null}
try:
    await flow_manager.initialize(initial_node)
except FlowError as e:
    logger.error(f"Flow error: {e}")
```

## FlowInitializationError

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
class FlowReferenceError(FlowError)
```

Raised when a flow config's references cannot all be resolved. Constructing a [`Flow`](/api-reference/pipecat-flows/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__()`

```python theme={null}
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}")
```

<ParamField path="problems" type="list[FlowProblem]">
  Every unresolved reference, in the order found. Also rendered into the
  exception's message, one per line.
</ParamField>

## FlowProblem

```python theme={null}
@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.

<ParamField path="code" type="str">
  Stable identifier for the kind of problem. See the table below.
</ParamField>

<ParamField path="message" type="str">
  Human-readable description naming the node, function, or handler involved.
</ParamField>

<ParamField path="node" type="str | None">
  The node the problem is about, when there is one. `None` for a problem in
  `global_functions`.
</ParamField>

<ParamField path="function" type="str | None">
  The function entry the problem is about, when there is one.
</ParamField>

### 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. |