> For the complete documentation index, see [llms.txt](https://docs.vdo.ninja/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vdo.ninja/guides/handling-guest-disconnects-and-connection-recovery.md).

# Handling Guest Disconnects and Connection Recovery

When guests randomly disconnect, freeze, or reconnect in loops, there is rarely one single fix. This guide gives a layered approach so you can choose the least disruptive option first, then escalate only when needed.

<figure><img src="/files/SrlPDVsfUmLueTv8OBER" alt="Diagram showing a guest disconnect recovery ladder from retry tuning to network checks, fallback transport, and live-show operational fallback"><figcaption><p>Start with URL-only recovery controls, then escalate toward relay, Meshcast, WHIP/WHEP, or live-show operational fallbacks only when needed.</p></figcaption></figure>

## Fast checklist before going live

1. Have guests use wired Ethernet where possible.
2. Ask guests on unstable links to test Chrome and Firefox ahead of time.
3. Keep a fallback path ready:
   * P2P first
   * Meshcast/WHIP+WHEP fallback
   * Mix-minus patching for critical audio continuity

## Option 1: URL-only recovery tuning (quickest)

Use these on room/director/push/view links as needed:

* `&autorecover=1` enables adaptive disconnect timing, TURN escalation, and eligible WHEP fallback signaling.
* Automatic relay escalation is enabled by default: direct P2P is tried first, a hard failure gets one normal ICE restart, and only a still-failed path gets one relay-eligible restart after the recovery window.
* `&autorelay=0`, `off`, `false`, or `no` disables forced-relay escalation. An explicit `&autorelay` value overrides the relay portion of `&autorecover` when both are present.
* `&p2pfailtimeout=<ms>` sets recovery timing window (default `12000`, clamp `3000-45000`).
* `&peerrecoversteps=<n>` sets retry depth (default `3`, clamp `1-6`).
* `&pendingicettl=<ms>` controls queued ICE candidate retention (default `15000`, clamp `3000-60000`).

Suggested presets:

* Balanced:
  * `&autorecover=1&p2pfailtimeout=12000&peerrecoversteps=3&pendingicettl=15000`
* Aggressive recovery:
  * `&autorecover=1&p2pfailtimeout=7000&peerrecoversteps=5&pendingicettl=20000`
* High-latency environments:
  * `&autorecover=1&p2pfailtimeout=18000&peerrecoversteps=4&pendingicettl=30000`

## Option 2: Browser and network remediations

* Switch guest browser (Chrome <-> Firefox) for problematic links.
* Disable VPN/proxy/security middleboxes where possible.
* Prefer Ethernet over Wi-Fi; avoid double-NAT and overloaded consumer routers.
* If direct P2P is consistently failing, test TURN path reliability using [`&relay`](/advanced-settings/turn-and-stun-parameters/and-relay.md).

## Option 3: Meshcast or WHIP/WHEP fallback

If room topology is large or network quality is inconsistent:

* Publish through Meshcast / WHIP and distribute WHEP playback where appropriate.
* Use `&whepshare=` (+ optional `&whepsharetoken=`) for external WHEP sources.
* Keep P2P for low-latency workflows, but use WHIP/WHEP paths when consistency is more important than absolute lowest latency.

## Option 4: Director operational fallback

When a specific guest-to-guest P2P edge fails during a live show:

* Ask the publisher to speak, click **Refresh** in **Mesh Network Debug**, and inspect the separate publisher -> listener arrow. Orange can identify a one-way RTP stall even while ICE remains connected.
* Select the affected arrow and use **Restart This ICE Path** before using guest-wide recovery actions.
* For one-way audio, prefer the listener's per-guest **Mix** control over the bidirectional **Patch via Mix-Minus** edge action. Both require an existing director outbound audio sender and can duplicate audio if the direct path recovers.
* Use **Restart All ICE Paths**, **Refresh Video**, **Refresh Mic**, or **Refresh Guest Media + ICE** when broader per-guest recovery is needed.
* If Mesh Network Debug confirms that a guest's primary WHIP publisher is restartable, use **Restart Primary WHIP**. If only this director's WHEP playback leg failed, use **Reconnect Local WHEP** instead.

See [Guest Audio Recovery and Mesh Debug](/guides/mesh-network-debug.md) for the directional health indicators, targeted ICE restart, mix-minus fallback, and safe operating sequence.

## Broadcast-mode resiliency pattern

For larger productions:

* Use broadcast-oriented workflows so not every guest must maintain every P2P edge.
* Keep a dedicated fallback scene/source path in OBS for temporary degraded guests.
* Combine with retry/reload controls for unattended overlays:
  * `&retry`
  * `&retrytimeout=5000`
  * `&autoreload` / `&autoreload24`

## Example link templates

* Director:
  * `https://vdo.ninja/?director=ROOM&autorecover=1&peerrecoversteps=4&p2pfailtimeout=9000`
* Guest:
  * `https://vdo.ninja/?room=ROOM&push=GUESTID&autorecover=1`
* Viewer/Scene:
  * `https://vdo.ninja/?scene&room=ROOM&retry&retrytimeout=5000`

## Related

* [Primary and Backup Guests with `&scene` and `&slots=1`](/guides/primary-and-backup-guests-with-scene-and-slots.md)
* [Mesh Network Debug](/guides/mesh-network-debug.md)
* [`&autorecover`](/advanced-settings/settings-parameters/and-autorecover.md)
* [`&autorelay`](/advanced-settings/turn-and-stun-parameters/and-autorelay.md)
* [`&p2pfailtimeout`](/advanced-settings/settings-parameters/and-p2pfailtimeout.md)
* [`&peerrecoversteps`](/advanced-settings/settings-parameters/and-peerrecoversteps.md)
* [`&pendingicettl`](/advanced-settings/turn-and-stun-parameters/and-pendingicettl.md)
* [Packet Loss](/common-errors-and-known-issues/packet-loss.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.vdo.ninja/guides/handling-guest-disconnects-and-connection-recovery.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.