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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalsamba.com/reference/sdk/events/mediaconnectionfailed.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.