Understanding the STATE_MISMATCH Disconnect Reason
Learn what the STATE_MISMATCH disconnect reason means in LiveKit, including its causes, how it differs from PEER_CONNECTION_DISCONNECT, and what triggers this server-side response.
Last Updated:
Users may see that a participant has disconnected due to a STATE_MISMATCH. This article explains what this reason means and when you might encounter it.
Background
WebRTC media connections use ICE/STUN keep-alives to verify connectivity. If the server stops receiving keep-alives from the client for approximately 20 seconds, it assumes the media path is dead. The client typically detects a problem after 15 seconds and may try to reconnect.
Internally, the SFU maintains a detailed set of internal reasons to describe why a participant's session is being closed or disconnected (ParticipantCloseReason). These internal reasons are mapped to a simplified, public-facing enum called DisconnectReason, which is what clients receive.
What Is STATE_MISMATCH?
STATE_MISMATCH is a disconnect reason used by the SFU to indicate that the server and the client have fallen out of sync regarding the state of the media connection. This is distinct from issues with the signaling connection — it specifically relates to the media path (audio/video data).
Note: The internal-to-public mapping is not perfect in all cases. In scenarios where a precise match isn't available, the most semantically appropriate
DisconnectReasonis chosen — and sometimes that ends up beingSTATE_MISMATCH.
What Causes STATE_MISMATCH?
There are a few common causes where STATE_MISMATCH might be used:
Unclean Client Disconnects
If a client leaves a session without properly sending a LeaveRequest (due to a bug or abrupt shutdown), the server eventually detects the absence and initiates cleanup.
Client Crash
If the client crashes unexpectedly, it won't be able to notify the server of the disconnection. After a timeout, the server initiates disconnection.
Network Blackouts
In network blackouts, the client reconnect attempt never reaches the server, and the server then disconnects with STATE_MISMATCH.
STATE_MISMATCH vs. PEER_CONNECTION_DISCONNECT
It's important to distinguish STATE_MISMATCH from PEER_CONNECTION_DISCONNECT:
| Disconnect Reason | Description |
|---|---|
PEER_CONNECTION_DISCONNECT | Indicates that the media connection (not signaling) has been lost due to network issues — e.g., packet loss, firewall blocks, sudden IP changes. |
STATE_MISMATCH | Generally implies a timeout or disconnect event where the server and client disagree about the session's current state, often due to a client that has become unresponsive or disconnected in an unexpected way. |
While these scenarios can overlap, the key differences are:
STATE_MISMATCHis more about inconsistency or lack of coordination in session lifecycle handlingPEER_CONNECTION_DISCONNECTis a more direct consequence of media transport failure
Key Takeaways
STATE_MISMATCHindicates the server and client have fallen out of sync on media connection state- Common causes include unclean disconnects, client crashes, and network blackouts
- It differs from
PEER_CONNECTION_DISCONNECTin that it's about session state disagreement rather than direct transport failure - The server uses this reason after detecting prolonged absence of client keep-alives (~20 seconds)