How to recognize the CORS failure
| Check | Symptom | Meaning |
|---|---|---|
| Manifest blocked | The .m3u8 request fails before playback starts. | The origin needs Access-Control-Allow-Origin or the player needs a proxy. |
| Key blocked | The manifest loads, but encrypted playback fails. | The AES-128 key URL must also allow CORS or route through the same proxy. |
| Segments blocked | Playback starts, then buffers or stalls. | Every .ts or .m4s segment request needs the same CORS path. |
| VLC works, browser fails | Desktop playback works but web playback does not. | This usually confirms a browser CORS problem, not a broken stream. |
| Preflight fails | Custom headers trigger an OPTIONS request that the origin rejects. | Avoid unnecessary headers or configure the proxy/origin to handle OPTIONS. |
How to fix or test an HLS CORS error
- 1
Check whether the manifest loads
Open the M3U8 URL or paste it into the player. If the manifest request is blocked by CORS, playback cannot even start.
- 2
Compare with VLC
If VLC can play the same URL but the browser cannot, the stream is probably reachable and the failure is browser access control.
- 3
Enable the smart CORS proxy
Turn on the proxy so manifests, encryption keys, and media segments all travel through a response that the browser can read.
- 4
Run the health report
Use the validator through the proxy to check whether segments are actually alive instead of just blocked by CORS.
- 5
Add Referer only when needed
If the origin uses hotlink protection, set the original page URL as Referer. Do not add custom headers unless the origin requires them.
Why HLS needs CORS on more than one URL
An HLS player does not fetch only one file. It fetches a master manifest, one or more media playlists, encryption keys for AES-128 streams, and many segment URLs. A single missing CORS header on any of those resources can break playback, so testing only the first .m3u8 response is not enough.
What Access-Control-Allow-Origin should do
For public streams, the origin can send Access-Control-Allow-Origin for the site hosting the player, or use a wildcard when credentials are not involved. For private streams, keep the origin locked down and use a controlled proxy endpoint for testing. Avoid mixing direct and proxied URLs in the same HLS session.
Why a proxy is useful for debugging
A proxy lets the browser request HLS assets from your own allowed origin while the proxy fetches the real manifest, key, and segment URLs. That makes it possible to tell whether a stream is broken or merely blocked by browser policy. It also gives you one place to add Referer or User-Agent when the origin requires them.
Related stream debugging tools
- M3U8 link troubleshooting covers CORS, Referer, dead segments, codec limits, and DRM.
- Custom Referer M3U8 player explains hotlink-protected streams that need forwarded headers.
Frequently asked questions
What causes an HLS CORS error?
An HLS CORS error occurs when the browser cannot read the M3U8 manifest, encryption key, or media segments because the origin did not allow cross-origin access. VLC can still play the stream because CORS is enforced by browsers.
Why does my M3U8 stream play in VLC but not Chrome?
VLC is not restricted by browser CORS checks. If VLC works and Chrome fails, the stream is usually reachable, but the browser cannot read one or more HLS requests without CORS headers or a proxy.
Can a CORS proxy fix M3U8 playback?
Yes, for testing and debugging. The proxy must route the manifest, media playlists, keys, and segments so every HLS request comes from an origin the browser is allowed to read.
Do HLS segments need CORS headers?
Yes. The manifest, child playlists, keys, and every media segment need to be readable by the browser. A stream can fail even if the top-level .m3u8 file has correct CORS headers.
Is this the same as hotlink protection?
No. CORS is a browser access rule. Hotlink protection is an origin rule that may require a specific Referer or User-Agent. Some streams have both problems, so you may need a proxy plus a matching Referer.