Troubleshooting

Troubleshooting

Problem	Reason	Solution
The custom frame processor does not handle the new pipeline creation and resets	The method process_frame() was overridden but does not call base class method super().process_frame() that handles relevant system frames like StartFrame, CancelFrame, and StartInterruptionFrame.	Ensure to always call super().process_frame() at the beginning of the method.
The frame processor is not resetting its state when the bot is interrupted by the user	StartInterruptionFrame is not handled	Handle StartInterruptionFrame frame in process_frame() function properly.
The Pipeline no longer works after changing the frame processor pipeline order.	The frame processors depend on specific input frames (refer to the frame processor source code documentation). By changing the frame processor order, expected frames might not yet be generated or already be consumed in the pipeline.	Inspect frame generation by enabling the TRACE logging level and make sure that the frame processors receive the expected frames.
Frames are not received in the frame processor later in the pipeline or in transport out	Frames are consumed by earlier frame processors, removing them from downstream.	Push the frame again into the corresponding frame processor. Alternatively, if you cannot change that, push a new frame type that will not be consumed by the frame processor.
Frames seem to be getting lost in the pipeline	The StartInterruptionFrame flushes all queues of all frame processors in the pipeline as soon as processed. This can lead to control or data frames getting lost. StartInterruptionFrame is of type SystemFrame and will immediately be processed by the next frame processor when pushed.	Ensure that the frame processors can handle missing data and control frames.
SystemFrame processing order in process_frame() is inconsistent with the frame input order	This is likely a consequence of how system frames are processed in Pipecat. A SystemFrame is immediately processed when pushed in the previous frame processor with push_frame(). The method process_frame() is called directly from push_frame(). This can lead to a chain of method calls resulting in a recursive execution of process_frame() when system frames are pushed up the pipeline again.	Delay the call of the push_frame() method either by moving it further down in process_frame() or by using an asyncio task to schedule the push_frame() with a minimal delay.