Guidance on handling network-level failures and recovery strategy in hls.js

[mudit2108]

Hi @robwalch,

For internalException errors, we already attempt bounded media recovery on the application side using recoverMediaError() (up to 6 retries). If recovery continues to fail, we stop retrying and surface a fatal UI to the user.

if (details === 'internalException' &&
this.getAttribute('refreshoninternalexception') === 'true') {
if (!this.attemptedErrorRecoveryCount ||
this.attemptedErrorRecoveryCount < 6) {
this.api.recoverMediaError();
this.attemptedErrorRecoveryCount =
(this.attemptedErrorRecoveryCount || 0) + 1;
} else {
// show fatal error UI
}
}

This works well for typical decode / append / MSE-related failures.

Where we still struggle is network-level failure scenarios, especially:

network switching (Wi-Fi ↔ cellular),
brief connectivity loss,
CDN edge issues where the response is neither a valid media segment nor a readable error body.
In these cases, the failure is not a bad segment, but also not a clean HTTP error. For a small subset of end users (observed via NEL logs), hls.js sometimes ends up in an internalException / invalid state that does not reliably recover, even though the network later stabilizes.

Unfortunately, this behavior is not reproducible locally, and the response itself is often missing or malformed, so providing a minimal repro or full console trace isn’t feasible.

What I’m trying to understand is:

From hls.js’ design perspective, how should applications handle these “network transition / no-response” cases?

Is repeatedly calling recoverMediaError() the correct approach here, or should this be escalated to a full loader restart (stopLoad() → startLoad())?
Are there signals or error types that indicate a network state issue vs a media pipeline issue?
Is there an expected recovery path when the fetch/XHR resolves but the response is unusable (neither text nor media)?
I’m not looking for a workaround specific to this issue as much as guidance on the intended recovery model for real-world network instability.

Any insight into how hls.js expects integrators to handle these cases would be really helpful. Thanks!

[robwalch]

v1.16.11 added handling for network connectivity issues. See #7476.

For bad responses that corrupt the stream you’ll have to do what you are doing or get your CDN to fix their delivery.