# Resilience & Failure Handling [← Back to Architecture Reference](https://kaltura.github.io/intelligent-agents-sdk/reference/architecture-reference/index.md) How `KalturaAvatarSession` behaves under network failures, disconnects, and device problems. Recovery has three layers. Each escalates to the next: | Layer | Scope | What the SDK does | Events | |---|---|---|---| | 1. Control socket | the websocket only | Socket.IO reconnects with backoff. If the socket state was recovered, the session goes straight back to `connected`. If not, the SDK does a cold reconnect (layer 3). The `reconnecting` state is bounded by `reconnectWindowMs` (default 22000). | `connectivityChanged` (`channel:'socket'`), `reconnecting`, `reconnected` | | 2. Media peers (ASR + STV) | one peer connection at a time | Watches ICE state, peer state and incoming video. Recovers in place first. If that fails, escalates to layer 3. | `connectivityChanged`, `mediaRecovering`, `mediaRecovered` | | 3. Cold reconnect | the whole conversation | Opens a new socket, re-`join`s, and rebuilds both media peers. Replays `threadId` so the conversation memory continues. Tries twice before it gives up. | `reconnecting`, `reconnected` | A non-recoverable failure ends the session cleanly (`ended`, or an error such as `reconnect_failed` or `reconnect_timeout`). It never hangs. A custom client that does not use `KalturaAvatarSession` must implement these layers itself. The rest of this page describes what the SDK does. ## Control socket - `maxReconnectAttempts` (default 5) caps Socket.IO's own attempts. It also appears as `attempt`/`maxAttempts` on `reconnecting` and `connectivityChanged`. - Recoverable disconnect reasons: `transport error`, `transport close`, `forced close`, `ping timeout`. Any other reason ends the session. - `reconnectWindowMs` (default 22000) bounds the whole `reconnecting` state. If nothing recovers in that time, the session ends with `reconnect_timeout`. If Socket.IO runs out of attempts first, it ends with `reconnect_failed`. - After a reconnect where the socket state was **not** recovered, the old session is gone. The SDK runs a cold reconnect (layer 3). - After a reconnect where it **was** recovered, the SDK also checks both media peers. A peer stuck in a down ICE state goes through layer 2. ## Media peers (ICE watch) | ICE state | SDK action | |---|---| | `disconnected` | Waits 1.5 s. If it has not returned to `connected`, recovers. | | `failed` | Recovers at once. | | `new` or `checking` for 10 s, or gathering ends with no candidates | Recovers. | | `connected` / `completed` | Clears the recovery flag. | The SDK emits `mediaRecovering { channel, state, cause }` when recovery starts and `mediaRecovered { channel, method }` when it works. Every ICE state change also emits `connectivityChanged { channel, state }`. | Channel | In-place recovery (`method`) | Details | |---|---|---| | ASR (mic uplink) | `ice-restart` | Restarts ICE on the same peer and re-offers over the socket with `is_reconnect: true`. Mute state is kept. Waits up to 30 s for the answer. | | STV (avatar video) | `re-subscribe` | Waits for the `DELETE` of the old WHEP resource, then sends a new WHEP offer. A `404` or `409` first asks for a new avatar session on the live socket ([details](https://kaltura.github.io/intelligent-agents-sdk/reference/wire-protocol/audio-channels/index.md#6-stv-downlink-pc2-avatar-videoaudio--you)). Then it resumes playback if the browser paused the element. | If in-place recovery fails, the SDK emits `connectivityChanged` with `state:'recover_failed'` and does a cold reconnect. `timeouts.recover` (15 s) bounds the STV re-subscribe. The ASR restart waits up to 30 s for its answer. Each channel has its own grace timer, so the two peers recover independently. The same recovery runs when the browser fires `online` after an `offline` and a peer is still in a down ICE state. Both events also emit `connectivityChanged` with `channel:'network'`. If the control socket is down while `reconnecting`, `online` makes it retry at once instead of waiting out its backoff. Turn this off with `networkAware:false`. ### ICE diagnostics Each peer keeps a safe summary of what it gathered and what its STUN and TURN servers answered. No address, port or credential is stored. `cause` names the most likely reason a path is not up: | `cause` | Meaning | What to do | |---|---|---| | `connected` | The media path is up | Nothing | | `turn_credentials_rejected` | The relay refused the credentials and no relay address was allocated | Check the TURN settings the session was given | | `turn_unreachable` | No relay address could be allocated | Allow outbound UDP and TCP on ports 80 and 443 to the relay host, or use another network | | `no_candidates` | The browser found no network address | Check the device is online, a VPN or privacy setting is not hiding its interfaces, and outbound UDP and TCP on ports 80 and 443 to the relay host are allowed | | `no_route` | Addresses exist but the media server was not reached | Try again, or use another network | | `closed` | The peer was closed (for example after `disconnect()`) | Nothing | | `still_gathering` | The browser was still looking for a path | Try again on a faster network | `await session.getIceReport()` returns `{ asr, stv }`. Each is `null` before that peer exists, or an `IceReport`: `channel`, the three peer states, `candidates` by type (`host`, `srflx`, `prflx`, `relay`), `errors` (`code`, `text`, `scheme`), `cause`, `hint` and `selectedPair` (`localType`, `remoteType`, `protocol`, or `null`). It never rejects and is safe to log or attach to a support ticket. `connect()` fails with `ice_failed` (`phase: 'ice'`, `retryable: true`, `error.ice` is the same summary) when the avatar peer never reaches ICE `connected`. This holds with or without a `