CodeCraft
← Back to Blog
Streaming2026-10-26·12 min read

HLS Stream Troubleshooting: Separate Playlist, Network, and Browser Errors

#hls#m3u8#streaming#cors#troubleshooting
C
CodeCraft Team· Engineering

When an HLS stream will not play, the visible symptom is often just a spinner or a short error message. The cause can be in a different layer: the playlist may be malformed, a child playlist or segment may be unreachable, the browser may block a cross-origin request, or the media codec may not be supported by that playback path.

This guide uses a repeatable workflow instead of treating every failure as an M3U8 syntax problem. It also explains what this site's [M3U8 Validator](/m3u8-validator) can confirm and what you still need to check in the [M3U8 Player](/m3u8-player) or your browser's Network panel.

1. Identify which playlist you have

An HLS URL can return a master playlist or a media playlist. A master playlist points to one or more variant playlists; a media playlist describes media segments. The distinction tells you which requests to test next.

A small master playlist:

#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=640x360,CODECS="avc1.4d401e,mp4a.40.2"
low/index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2400000,RESOLUTION=1280x720,CODECS="avc1.4d401e,mp4a.40.2"
high/index.m3u8

Each URI after #EXT-X-STREAM-INF points to another playlist. A successful response for the master file does not prove that either variant playlist or its segments are reachable.

A small video-on-demand media playlist:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXTINF:6.0,
segment-001.ts
#EXTINF:5.8,
segment-002.ts
#EXT-X-ENDLIST

The validator can identify common master/media playlist structures and show parsed variants or segments. It is a lightweight inspector, not a complete implementation of every HLS version or extension. For protocol requirements, compare the stream with RFC 8216.

2. Validate the response, not just the URL

Open the M3U8 Validator and test the URL. Check the HTTP status, response content type, and the beginning of the response body. A server can return HTTP 200 with an HTML login page, JSON error, or expired-link message instead of a playlist. A normal playlist begins with #EXTM3U.

If you already have the playlist text, use the paste mode. This checks its structure without making a request for the URL. Compare the output:

- URL fetch fails, but pasted text parses: investigate URL access, authentication, expiration, or the source server.

- URL fetch succeeds, but parsing reports errors: inspect the returned body and the reported playlist line or tag.

- The master parses, but playback still fails: continue with the child playlists and media requests.

For a media playlist, #EXT-X-TARGETDURATION is required by RFC 8216. The rounded duration of each segment must not exceed it. A missing #EXT-X-ENDLIST commonly means the playlist is live or still changing; it is not by itself proof of a malformed VOD stream.

3. Follow every request in the HLS chain

A player may request the master playlist, a selected variant playlist, media segments, encryption keys, and initialization data. Test the exact request that fails in the browser's Network panel. Look at the request URL, status, response body, and whether the request was blocked before a response arrived.

Common patterns:

- 403: the stream may require a valid signed URL, token, cookie, or request header. A URL can expire between validation and playback.

- 404: a referenced variant, segment, key, or initialization file may have moved, been removed, or been generated with the wrong relative path.

- CORS in the browser: the source must allow the page's origin for browser playback. A server-side URL check can succeed while the browser player is blocked, because the browser enforces CORS and a server-side request does not.

- Mixed content: an HTTPS page cannot load an HTTP playlist or media resource. Use HTTPS for the full request chain.

Relative segment and variant paths are resolved from the playlist that contains them. Check nested playlists independently; do not assume every path is relative to the original master URL. The validator's URL mode can help inspect a fetchable playlist, while the player reveals whether the browser can play the stream. Neither tool bypasses access controls or fixes headers on the source server.

4. Read the player's error category

This site's player displays the fatal hls.js error type and detail when playback stops. hls.js groups errors into categories such as networkError and mediaError; inspect the detail as well as the category. The hls.js error reference lists the names used by the library.

- A network error points you toward playlist, segment, key, status-code, or cross-origin requests. Confirm the failing request in Network before changing the playlist.

- A media error points you toward parsing, decoding, buffer, or MediaSource behavior. If requests succeed, check the stream's container and codecs against the browser's capabilities; a valid playlist does not guarantee decodable media.

- If the stream loads but does not start, press Play in the video controls. Browsers can block playback initiated without a user gesture.

- Compare another supported playback path, such as Safari's native HLS support or an MSE-based browser with hls.js. Different results help isolate browser or codec compatibility from a server-side failure.

Error messages are evidence, not a complete diagnosis. Record the browser, the failing request, and the exact error detail before changing the stream configuration.

5. Check encryption and live-stream expectations

The validator can report encryption metadata such as an #EXT-X-KEY tag, but it does not decrypt media. Ordinary HLS encryption and DRM license systems are different capabilities. A stream that requires a DRM license or protected key system will not become playable just because its playlist parses. Use only streams you are authorized to access.

For live streams, the media playlist is expected to change as new segments arrive, and the live window may remove older segments. A playlist without #EXT-X-ENDLIST is common for live delivery. If playback starts and later stalls, compare the playlist refreshes, segment availability, and segment durations with the target duration. RFC 8216 defines the playlist and update rules; the validator provides a quick view of common fields but does not monitor a live stream continuously.

A short decision path

Use this order to avoid changing unrelated settings:

1. Confirm the URL returns a playlist beginning with #EXTM3U, not an error page.

2. Parse it with the M3U8 Validator and identify master versus media playlist.

3. Check every nested playlist, segment, and key request in the browser Network panel.

4. If the browser reports CORS, fix the source server's response policy; client-side playlist edits cannot grant permission.

5. If requests succeed, use the player's error detail to investigate codec, media parsing, autoplay, or browser support.

6. Retest the same URL in the M3U8 Player after the relevant source-side change.

Keep the failing request and its response status with your notes. That makes the difference between a playlist defect, a delivery problem, and a browser limitation much easier to reproduce.

A playlist that parses is only one layer of a working stream. Validate its structure, verify each resource request in the browser, then use the player error category to investigate media and browser compatibility.