> For the complete documentation index, see [llms.txt](https://docs.digitalsamba.com/reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalsamba.com/reference/sdk/events/mediaconnectionfailed.md).

# mediaConnectionFailed

Emitted when the media plane (audio/video) cannot be established or sustained, even though the signaling connection (WebSocket) remains functional. This event lets integrators branch fallback UX — such as HLS playback, dial-in, or a custom retry flow — based on which direction failed and whether a fresh rejoin is likely to help.

The event fires once per failed peer connection for the remainder of that connection's lifetime. Rejoining the room or re-establishing a new peer connection starts a fresh evaluation.

### Sample payload

```json
{
  "type": "mediaConnectionFailed",
  "data": {
    "direction": "subscribing",
    "cause": "network_blocked"
  }
}
```

### Parameters

<table><thead><tr><th width="116.1015625">Parameter</th><th width="264.71875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>direction</code></td><td><code>'publishing' | 'subscribing'</code></td><td>Which media flow failed. <code>subscribing</code> — the participant cannot receive remote audio/video (silent room). <code>publishing</code> — the participant cannot deliver their own audio/video (others see/hear nothing from them). Both directions can fail independently and each triggers its own event.</td></tr><tr><td><code>cause</code></td><td><code>'network_blocked' | 'connection_failed'</code></td><td>Why the failure is terminal. <code>network_blocked</code> — the network prevented ICE from gathering any candidates (typically corporate DPI, strict firewall, or port restrictions blocking STUN/TURN). Rejoining the same room on the same network will fail identically. <code>connection_failed</code> — ICE gathered candidates but could not establish or maintain a working path, even after an automatic restart attempt. A fresh peer connection via rejoin may succeed if the underlying issue was transient.</td></tr></tbody></table>

### Usage example

```javascript
sambaFrame.on('mediaConnectionFailed', ({ direction, cause }) => {
  if (cause === 'network_blocked') {
    // Rejoining on the same network will not help.
    // Suggest switching networks, or swap to a fallback transport (e.g. HLS, dial-in).
    showNetworkBlockedFallback({ direction });
  } else {
    // cause === 'connection_failed' — the issue may be transient.
    // Offer a retry, or let the user dismiss and try rejoining.
    showConnectionFailedRetry({ direction });
  }
});
```

### Remarks

{% hint style="info" %}
The event pairs with the built-in "Media connection failed" modal, which shows direction- and cause-aware copy. Integrators implementing their own fallback UX can dismiss or hide the built-in modal.
{% endhint %}

* `cause: 'network_blocked'` corresponds to zero ICE candidates gathered after ICE negotiation. This is a strong signal of network-layer blocking.
* `cause: 'connection_failed'` fires when an ICE restart attempt fails to re-establish connectivity on a previously-negotiated peer connection.
* Fires independently for publishing and subscribing directions. A single session can emit both if both directions fail.
* Distinct from `connectionFailure`, which fires for signaling-layer (WebSocket) connection failures, not media-layer failures.