Realtime troubleshooting
Below are suggestions on how to fix some common problems with realtime sessions, each linking to the page that covers the underlying behavior. For issues not listed here or addressed in the documentation, see the general troubleshooting page, ask in the Pydantic Slack, or create an issue on GitHub.
Send mono PCM16 at session.audio_input_sample_rate and play it at
session.audio_output_sample_rate. Do not assume the rates match. See the
audio wire contract.
In push-to-talk mode, call commit_audio() and then create_response() after sending audio. See
push-to-talk.
send('...') already asks the model to reply. Do not follow it with create_response(), which asks
for a second response. See text turns.
The microphone is probably hearing speaker output. Add echo cancellation in the device/WebRTC layer and stop local playback on real barge-in.
Speaker echo or microphone transients probably cancelled the greeting while the audio path opened.
Mute microphone capture until the greeting has played, while continuing to send digital silence so
server VAD can close any open speech segment; see Muting the microphone
and Speaking first.
To confirm the cause, iterate the event stream and look for a
RealtimeResponseInterruptedEvent on the
first response and any
RealtimeSessionErrorEvent, or inspect the
Logfire trace.
The local tool runs concurrently, but the provider may pause speech while awaiting the result. Show tool lifecycle events and review concurrent tool execution.
Inspect RealtimeSessionReconnectEvent.state_restored. If false, the drop cut off a turn in flight:
the session closed any cut reply as interrupted and kept the earlier turns, so ask again or resend
the cut turn rather than starting over. On Gemini, a drop before the first resumption handle starts
a fresh session, which gets the earlier turns replayed from the session’s history and is asked again
for the reply to a typed turn the drop caught before its reply started. If true but a current
utterance vanished, that in-flight media was outside the restored completed-turn history. See
state restoration.
GPT-Live sends the agent’s instructions and system prompt only to the backend model that does
delegated work, never to the voice model the caller hears. Put the persona, language, and speaking
style in openai_live_instructions. See How delegation works.
Set the reconnect setting to a ReconnectPolicy; Gemini
session resumption is enabled automatically alongside it. Recovery uses the latest in-memory server
handle after the drop. See Gemini session resumption and
provider session limits.
Cascade models such as gpt-5 and gpt-4.1 speak only through Azure text-to-speech voices, so
they reject openai_voice. Choose their voice with azure_voice_live_voice instead. See
Voice Live voices.
The connect-time preflight raises a UserError naming what to change: an
override toggle the agent doesn’t permit (see
Configuration ownership), or a difference between the session’s tools and
the agent’s client tools (see Tool synchronization). A bad API key or an
unknown agent id raises a ModelHTTPError instead.