> For the complete documentation index, see [llms.txt](https://docs.cstplus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cstplus.org/documentation/troubleshooting/stream-and-playback-issues.md). # Stream and Playback Issues ### Viewers get 403 Forbidden {% tabs %} {% tab title="Wrong credentials" %} The line username or password is incorrect. Verify on the Lines page in the panel that the credentials match exactly what the viewer is entering. Credentials are case-sensitive. {% endtab %} {% tab title="Line disabled" %} The line may be disabled or expired. Check the line status on the Lines page. Re-enable it or extend the expiry date if needed. {% endtab %} {% tab title="Geo-blocked" %} The viewer's country may be blocked at the global level (Settings > Security) or on the specific line. Check both places. {% endtab %} {% tab title="Wrong channel" %} The line may not have access to the specific channel being requested. Check the line's channel access setting and make sure the channel is included. {% endtab %} {% endtabs %} *** ### Viewers get 404 on stream URL A 404 on a stream URL means one of: 1. **The channel is not on air.** Check channel status on the Channels page. Start it if needed. 2. **The channel slug in the URL is wrong.** Slugs are case-sensitive. Copy the URL directly from the Lines detail page. 3. **License enforcement is active.** If the license expired, the edge purges HLS files and returns 404. Reactivate the license. *** ### Viewers get 429 Too Many Requests The line has hit its `max connections` limit. Options: * **Kill idle connections** from the Dashboard connections panel * **Increase the limit** on the line's detail page * **Create a separate line** with a higher limit for the affected viewer *** ### Stream plays but has no video (black screen) 1. Open the stream in VLC: `vlc YOUR_STREAM_URL`. If it plays in VLC, the issue is in the viewer's app or device. 2. If black in VLC as well, check the channel render warnings. A render that only produced audio tracks will play silence with a black frame. 3. Verify the source files have video: `ffprobe YOUR_FILE.mp4 | grep Video` *** ### Stream buffers or stutters {% tabs %} {% tab title="Server bandwidth" %} Check network usage on the Dashboard. If outbound bandwidth is saturated, add an edge node or move to a server with more bandwidth. A 720p HLS stream uses roughly 2-4 Mbps. A 1080p stream uses 4-8 Mbps. Multiply by concurrent viewers. {% endtab %} {% tab title="Viewer connection" %} Ask the viewer to test with a lower-quality channel first. If lower quality plays fine but HD stutters, the issue is their connection, not the server. {% endtab %} {% tab title="Segment size" %} If many viewers buffer at the same time at regular intervals, the HLS segment size may be too large. Reduce `hls_time` in Settings > Streaming (default is 4 seconds; try 2). Restart affected channels after changing this setting. {% endtab %} {% endtabs %} *** ### EPG is blank or shows wrong times {% tabs %} {% tab title="No EPG in app" %} The EPG URL must be included in the M3U playlist for the app to load it. Copy the M3U URL from the Lines detail page rather than constructing it manually. The pre-built URL includes `url-tvg` pointing to the correct XMLTV endpoint. {% endtab %} {% tab title="Wrong times" %} EPG times are anchored to the **server timezone** set in Settings > General. If EPG times are offset from what you expect, check that the timezone is set correctly and restart the control plane: ```bash systemctl restart cstplus-control ``` {% endtab %} {% tab title="Titles are filenames" %} EPG titles are derived from filenames when no TMDB key is set. To get proper titles and descriptions, add a TMDB API key in Settings > API and click **Apply to all** on the channel's program metadata editor. {% endtab %} {% endtabs %} *** ### Continuous TS stream returns 403 Continuous TS URLs require a signed HMAC token in addition to line credentials. If you are constructing the URL manually, the token is missing. Use the URL from the Lines detail page, which includes the correct signed token. Tokens are session-bound and cannot be reused across connections. *** ### Web player returns "Token invalid" Web player tokens expire after a short period. Refresh the page to get a new token. If this keeps happening, check that your server's system clock is accurate: ```bash timedatectl status ``` If the clock is skewed, token validation will fail. Enable NTP sync: ```bash timedatectl set-ntp true ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cstplus.org/documentation/troubleshooting/stream-and-playback-issues.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.