Resilience & Failure Handling

← Back to Architecture Reference

How KalturaAvatarSession behaves under network failures, disconnects, and device problems. Recovery has three layers. Each escalates to the next:

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)

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

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:

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 <video> element and with or without a frame callback: connect() never resolves while ICE is down. ICE failed ends the wait at once. Otherwise the wait ends at timeouts.firstFrame. The first miss re-subscribes once. The second miss rejects. A peer that is connected but shows no frame is a different case: connect() resolves with media_no_video. An ASR peer that fails while connect() is still running is recovered as soon as the session is connected.

Peer health watchdog

A peer can die without an ICE event: closing it from outside fires nothing, and a stalled sender keeps ICE connected while no video arrives. While the session is connected (not paused or released), a check runs every timeouts.healthTick (1 s):

Both go through the same recovery as an ICE failure and emit the same events. A peer that reports no video receiver is not judged. A sender that stays stalled gets two re-subscribes in a row. If video still does not flow, the next stall does a cold reconnect. The watchdog stops on disconnect().

Cold reconnect retries

A cold reconnect makes up to timeouts.coldAttempts (2) attempts, timeouts.coldBackoff (500 ms) apart. A failed first attempt emits connectivityChanged { channel:'socket', state:'reconnect_retry' }. When the last attempt fails, the session emits error and then ended, both with reconnect_failed (phase: 'reconnect', retryable: true). error.cause holds the last attempt's error. disconnect() during the backoff cancels the retry.

Recovery events

Timeouts

All keys go in cfg.timeouts of a KalturaAvatarSession. In a KalturaAgentSession, put it inside the avatar option. Unset keys keep the default.

The connect-time keys (overall, joinRoom, and the rest) are in Connection & Handshake.

Device permissions (mic)

connect() starts getUserMedia({audio}) in the background (micStartMode: 'immediate', the default). It asks for audio only. The avatar does not need your camera.

• A denied, missing or busy mic does not fail connect(). The SDK emits one warning and connects without a mic. speak() still works, and startMic() retries.
• startMic() throws the same codes.
• micStartMode:'deferred' skips the automatic prompt. Call startMic() from a user gesture.

Failure-mode matrix

Tool-call spiral

An agent can retry the same client command again and again instead of narrating. KalturaAvatarSession breaks the loop in two steps. KalturaChatSession has the first step only, because a chat turn has no socket to rebuild.

Set recoverFromSpiral:false to resend the turn yourself from lastTurnText. Set any of the three limits to 0 to turn that step off. Options and a code sample: README § Resilience: agent stalls and tool-call spirals. Prompt-side prevention: Client-Side Commands.

Session completion

All three session classes send session_completed when a conversation truly ends: disconnect(), idle logoff, tab close, or a long background. Triggers, options and the cross-tab rule: README § Ending a conversation cleanly. Request shape: Conversation & Analytics § Session-Completion Signal.

Page exit

A pagehide that is not a bfcache freeze runs disconnect(). The session sends session_completed first, then DELETEs the WHEP resource with keepalive so the request outlives the page, closes both peers and closes the socket. It is installed when connect() starts, so a tab closed mid-connect is cleaned up too. A request already in flight is aborted, and a DELETE can only name a resource whose answer has arrived. The browser decides whether a request sent while a page closes completes, so the release is best effort. A pagehide with persisted:true (bfcache freeze) leaves the session alone. Turn the whole page-lifecycle handling off with pageLifecycleAware:false.

Related docs