FrameProcessor Events

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_usable_changed`	The processor’s ability to do its job changed
`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.

@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.processor and not error.processor.is_usable:
        print("This processor can no longer do its job")

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
category (ErrorCategory | None): What kind of failure it was, e.g. AUTHENTICATION or SERVER
processor (FrameProcessor | None): The processor that originated the error. Its is_usable already reflects this error, so reading it here tells you whether the processor is finished or merely had a bad moment
fatal (bool): Deprecated in v1.8.0, removed in 2.0.0. Check processor.is_usable instead

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.

on_usable_changed

Fired when the processor’s ability to do its job changes, in either direction — when an error leaves it unable to work, and again when set_usable(True) brings it back.

@tts.event_handler("on_usable_changed")
async def on_usable_changed(processor, is_usable):
    if not is_usable:
        await page_oncall(f"{processor} is down")

Parameters:

Parameter	Type	Description
`processor`	`FrameProcessor`	The processor whose verdict changed
`is_usable`	`bool`	Whether it can be given work

See Error Handling for what makes a processor unusable and what the pipeline does about it.

Example: Error handling across multiple processors

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.

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

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

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

@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

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.

Events - Overview of all events in Pipecat
PipelineWorker - Pipeline lifecycle events
Observer Pattern - Non-intrusive pipeline monitoring

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

FrameProcessor Events

Overview

Events Summary

Error Handling

on_error

on_usable_changed

Example: Error handling across multiple processors

Frame Processing Hooks

on_before_process_frame

on_after_process_frame

on_before_push_frame

on_after_push_frame

​Overview

​Events Summary

​Error Handling

​on_error

​on_usable_changed

​Example: Error handling across multiple processors

​Frame Processing Hooks

​on_before_process_frame

​on_after_process_frame

​on_before_push_frame

​on_after_push_frame

​Related

Overview

Events Summary

Error Handling

on_error

on_usable_changed

Example: Error handling across multiple processors

Frame Processing Hooks

on_before_process_frame

on_after_process_frame

on_before_push_frame

on_after_push_frame

Related