> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FrameProcessor Events

> Handle errors and monitor frame processing with events available on every processor

## Overview

Every frame processor in Pipecat — including all services, transports, and custom processors — inherits from `FrameProcessor` and exposes a set of events for error handling and frame monitoring. These events are **synchronous**, meaning handlers run inline and must execute quickly to avoid blocking the pipeline.

## Events Summary

| Event                     | Description                                         |
| ------------------------- | --------------------------------------------------- |
| `on_error`                | An error occurred in this processor                 |
| `on_before_process_frame` | A frame is about to be processed                    |
| `on_after_process_frame`  | A frame has just been processed                     |
| `on_before_push_frame`    | A frame is about to be pushed to the next processor |
| `on_after_push_frame`     | A frame has just been pushed to the next processor  |

## Error Handling

### on\_error

Fired when an error occurs in this processor. This is called before the `ErrorFrame` is pushed upstream through the pipeline, giving you an opportunity to handle errors at the processor level.

```python theme={null}
@tts.event_handler("on_error")
async def on_tts_error(processor, error):
    print(f"Error in {processor}: {error.error}")
    if error.exception:
        print(f"Exception: {error.exception}")
    if error.fatal:
        print("This is a fatal error — pipeline will be cancelled")
```

**Parameters:**

| Parameter   | Type             | Description                              |
| ----------- | ---------------- | ---------------------------------------- |
| `processor` | `FrameProcessor` | The processor where the error occurred   |
| `error`     | `ErrorFrame`     | The error frame containing error details |

The `ErrorFrame` provides:

* `error` (str): The error message
* `exception` (Exception | None): The underlying exception, if any
* `fatal` (bool): Whether this is a fatal error that will cancel the pipeline
* `processor` (FrameProcessor | None): The processor that originated the error

<Note>
  Since `on_error` is synchronous, the handler runs before the error frame
  propagates upstream. Keep your handler fast — use it for logging or setting
  flags, not for I/O operations.
</Note>

### Example: Error handling across multiple processors

```python theme={null}
async def handle_service_error(processor, error):
    logger.error(f"Service error in {processor.name}: {error.error}")
    # Notify monitoring system, set a flag, etc.

# Register the same handler on multiple services
stt.add_event_handler("on_error", handle_service_error)
tts.add_event_handler("on_error", handle_service_error)
llm.add_event_handler("on_error", handle_service_error)
```

## Frame Processing Hooks

These events let you observe frames as they flow through a processor. They're useful for debugging, logging, or lightweight monitoring.

### on\_before\_process\_frame

Fired immediately before a frame is processed by this processor's `process_frame()` method.

```python theme={null}
@stt.event_handler("on_before_process_frame")
async def on_before_process(processor, frame):
    print(f"{processor} is about to process: {frame}")
```

**Parameters:**

| Parameter   | Type             | Description                              |
| ----------- | ---------------- | ---------------------------------------- |
| `processor` | `FrameProcessor` | The processor about to process the frame |
| `frame`     | `Frame`          | The frame about to be processed          |

### on\_after\_process\_frame

Fired immediately after a frame has been processed by this processor's `process_frame()` method.

```python theme={null}
@stt.event_handler("on_after_process_frame")
async def on_after_process(processor, frame):
    print(f"{processor} finished processing: {frame}")
```

**Parameters:**

| Parameter   | Type             | Description                            |
| ----------- | ---------------- | -------------------------------------- |
| `processor` | `FrameProcessor` | The processor that processed the frame |
| `frame`     | `Frame`          | The frame that was processed           |

### on\_before\_push\_frame

Fired immediately before a frame is pushed to the next processor in the pipeline.

```python theme={null}
@llm.event_handler("on_before_push_frame")
async def on_before_push(processor, frame):
    print(f"{processor} is about to push: {frame}")
```

**Parameters:**

| Parameter   | Type             | Description                     |
| ----------- | ---------------- | ------------------------------- |
| `processor` | `FrameProcessor` | The processor pushing the frame |
| `frame`     | `Frame`          | The frame about to be pushed    |

### on\_after\_push\_frame

Fired immediately after a frame has been pushed to the next processor in the pipeline.

```python theme={null}
@llm.event_handler("on_after_push_frame")
async def on_after_push(processor, frame):
    print(f"{processor} pushed: {frame}")
```

**Parameters:**

| Parameter   | Type             | Description                         |
| ----------- | ---------------- | ----------------------------------- |
| `processor` | `FrameProcessor` | The processor that pushed the frame |
| `frame`     | `Frame`          | The frame that was pushed           |

<Warning>
  All frame processing events are **synchronous** — handlers block the pipeline
  until they complete. Avoid any I/O, `await` calls to external services, or
  other slow operations in these handlers. Use them only for fast operations
  like logging, counting, or setting flags.
</Warning>

## Related

* [Events](/api-reference/server/events/overview) - Overview of all events in Pipecat
* [PipelineTask](/api-reference/server/pipeline/pipeline-task#event-handlers) - Pipeline lifecycle events
* [Observer Pattern](/api-reference/server/utilities/observers/observer-pattern) - Non-intrusive pipeline monitoring