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

Related

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