What is an HLS playback problem?
An HLS player starts by requesting a manifest (.m3u8). A master manifest lists variants at
different bitrates and resolutions; the player picks one and requests its media playlist, which lists
segment files. It then downloads segments, optionally fetches an encryption key, and passes the media to
the browser, either through Media Source Extensions (hls.js, Video.js) or native HLS support (Safari and
most iOS browsers). A failure at any step looks like "the video does not play", so the first job is
working out which step failed.
Common reasons an M3U8 URL does not work
- Incorrect URL: a typo, wrong path, or a page URL instead of the playlist URL.
- Server errors: the origin or CDN returns 4xx or 5xx responses.
- CORS restrictions: the server does not allow your site's origin to read the response from JavaScript.
- Authentication and signed URL expiry: tokens that are missing, invalid, or past their lifetime.
- Invalid playlist syntax: no
#EXTM3Uheader, missing segment URIs, or HTML returned instead of a playlist. - Missing segments: the playlist is fine but segment paths are wrong or files were deleted.
- Unsupported codecs: the browser cannot decode the video or audio inside the segments.
- Player configuration: wrong source type, missing hls.js setup, or a conflicting
crossoriginattribute. - Encryption and DRM: keys or licenses the player cannot obtain.
- Live-stream timing: a stalled encoder, a stale playlist, or a player too far behind the live edge.
How to debug HLS in browser Developer Tools
- Open DevTools (F12) and reload with the Network panel open. Enable "Preserve log" if the page navigates.
- Filter by
m3u8, thents,m4s, ormp4. Check the status code of each request. - Click a failed request and read the Response Headers. For CORS issues, look for
Access-Control-Allow-Origin. - Open the response body of the manifest. It should start with
#EXTM3U, not HTML. - Read the Console. A red CORS message means the browser blocked access; a request with a 404 or 403 status means the server answered.
- If every request succeeds but nothing plays, suspect codecs, a decoder limit, or a player setting rather than the server.
How to fix common HLS errors
| Error | What to do |
|---|---|
| CORS error on manifest | On a server you control, return Access-Control-Allow-Origin for your site's
origin on the manifest, child playlists, segments, and keys. Handle OPTIONS
preflight if you send custom headers. |
| 403 Forbidden | Check token validity, referrer or IP rules, and hotlink protection. Compare the request headers in the Network panel with a request that works. |
| 404 on segments | Compare the resolved segment URL with the files on the origin. Check relative paths, CDN path prefixes, and whether old segments were cleaned up too early. |
| "Unexpected token '<'" | The server returned HTML. Open the response body: it is usually a login page, error page, or SPA fallback route. |
| bufferAppendError / MEDIA_ERR_DECODE | Inspect codecs with ffprobe. Make sure all segments use consistent codecs
and timestamps, and re-encode with widely supported profiles (H.264 + AAC). |
| Stalls on a live stream | Reload the playlist several times. If it does not advance, the problem is at the encoder or origin. If it does, adjust live sync and buffer settings in the player. |
HLS Troubleshooter vs M3U8 Analyzer vs M3U8 Validator
- Troubleshooter (this page): helps investigate likely causes of playback failures from a URL or an error message.
- M3U8 Analyzer: inspects playlist structure, tags, variants, and metadata.
- M3U8 Validator: checks playlist structure against selected syntax and consistency rules. This page runs only basic structural checks and is not a conformance validator.
Troubleshooting limitations
- Browser CORS restrictions may prevent remote inspection entirely.
- A valid manifest can still fail because of the resources it references.
- A successful HTTP request does not guarantee media playback.
- Some errors need Developer Tools, server logs, CDN logs, or authorized credentials to diagnose.
- A URL may stop working after this page checks it, and a single snapshot cannot show how a live stream behaves over time.
- Browser capability checks are not full playback certification.
- This tool does not bypass access controls or DRM.
Developer note: the tool is a standalone page and has not been verified against live servers in every
browser; behavior of fetch() on cross-origin responses varies by browser and server
configuration. If you ever add a server-side fetcher, it needs its own SSRF protection; the
local-address filter on this page is not a substitute.
FAQ
Why does my M3U8 URL work directly but not in my website?
Opening a URL in a tab is a navigation, which is not subject to CORS. Your website's JavaScript is making a cross-origin request, so the stream's server must send suitable CORS headers. Other causes include referrer or domain restrictions, mixed content (HTTP stream on an HTTPS page), and a player that does not support HLS in that browser.
How do I fix an HLS CORS error?
Configure the server or CDN that hosts the resource, which you must control, to send
Access-Control-Allow-Origin for your origin. Apply it to the manifest, child playlists,
segments, and any keys. You cannot fix it from your page, and mode: "no-cors" only
produces an unreadable opaque response.
What does a 403 error mean for an M3U8 stream?
The server understood the request and refused it. Reasons include an invalid or expired token, a referrer or IP restriction, hotlink protection, or a permission rule. A 403 does not by itself prove the URL has expired.
Why does my player show a black screen?
Common causes are a failed segment request, unsupported codecs, a decoder error, an autoplay restriction with audio, or a player that never attached to the video element. Check the Network and Console panels to see which applies.
Why does an M3U8 URL return HTML instead of a playlist?
The server is probably returning a login page, an error page, a redirect target, or a single-page app
fallback. Open the response body and check the first line; a real playlist starts with
#EXTM3U.
Can an M3U8 URL be valid but still fail to play?
Yes. The manifest can be correct while segments are missing, blocked, or encoded with codecs the device cannot decode. Encryption keys and DRM licenses can also fail independently of the manifest.
How do I troubleshoot HLS on mobile browsers?
iOS browsers use native HLS and do not support hls.js through Media Source Extensions on iPhone in
the same way as desktop. Test with the native player, check autoplay and playsinline
rules, confirm that codecs match the device, and use remote debugging (Safari Web Inspector or
Chrome DevTools) to read the Network panel.
Can this tool test DRM-protected streams?
No. It can point out HLS encryption metadata such as #EXT-X-KEY, but it does not obtain
keys or licenses, and it does not bypass DRM. Use a supported player and license workflow for
content you are authorized to access.
Why can the tool not inspect my URL?
Most often the stream's server does not allow cross-origin reads from this page, so the browser hides the response. The server might also be unreachable, slow, or blocking the request. Use your browser's Network panel for the real details.
Does this tool store my stream URL?
The page does not use cookies, local storage, or analytics for your input, and Reset clears the fields and results. Your browser still sends the request to the stream's own server, which can log it.