> 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/channel-issues.md).

# Channel Issues

### Channel is stuck on "Rendering"

Rendering is done by ffmpeg. If it has been running for much longer than expected, check:

```bash
journalctl -u cstplus-control -n 100 | grep render
```

Also check if ffmpeg is actually running:

```bash
ps aux | grep ffmpeg
```

**If ffmpeg is running but progress is not moving**, the most common cause is a corrupt source file that ffmpeg is struggling to decode. Check the render warnings on the channel page after it completes or fails.

**If ffmpeg is not running**, the render queue may have stalled. Restart the control plane:

```bash
systemctl restart cstplus-control
```

Then click **Re-render** on the channel.

{% hint style="info" %}
If you have `max_concurrent_renders` set to 1 in Settings > Rendering and another channel is already rendering, the second render will wait in the queue. This is normal.
{% endhint %}

***

### Render completed but channel shows warnings

CST+ skips files it cannot read and collects warnings instead of hard-failing. Warnings appear on the channel card and channel page.

Common warning causes:

| Warning                 | Cause                                                |
| ----------------------- | ---------------------------------------------------- |
| `no video stream found` | The file has audio only or is not a valid video file |
| `probe failed`          | File is corrupt or in an unsupported format          |
| `encode failed`         | ffmpeg failed to transcode this specific file        |

Remove the problematic files from the content folder and click **Re-render**.

***

### Channel will not start after rendering

Check the channel's systemd service:

```bash
systemctl status "cstplus-channel@YOUR_SLUG"
journalctl -u "cstplus-channel@YOUR_SLUG" -n 50
```

Common causes:

| Error                        | Fix                                                                                 |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| `rendered reel not found`    | The render did not complete successfully. Click Re-render.                          |
| `HLS directory not writable` | Permissions issue on `/opt/cstplus/hls/`. Run `chown -R root:root /opt/cstplus/hls` |
| `ffmpeg not found`           | ffmpeg was removed or its path changed. Reinstall: `apt-get install -y ffmpeg`      |

***

### Channel shows "Error" status

An on-air channel that crashes lands in Error state. The error message is shown on the channel page.

To restart it, click **Start** on the channel page. If it crashes again immediately, check the service logs:

```bash
journalctl -u "cstplus-channel@YOUR_SLUG" -n 50 --no-pager
```

{% hint style="warning" %}
A channel that crash-loops usually has a bad rendered reel. Click **Re-render** to rebuild it from scratch.
{% endhint %}

***

### Re-render does not pick up new files

After adding files to the content folder, click **Re-render** on the channel page. CST+ does not watch the folder for changes automatically.

If you clicked Re-render but the new files are not appearing in the rendered output, verify:

1. The files are in the exact content folder set on the channel (check the path in channel settings)
2. The files are playable: test with `ffprobe YOUR_FILE.mp4`
3. The render completed without errors (check the warnings section on the channel page)

***

### Schedule mode channel is out of sync with EPG

The channel seeks to the correct clock position on every start. If the channel has been running without a restart and you notice drift between what is playing and what the EPG says, restart the channel:

Click **Restart** on the channel page, or:

```bash
systemctl restart "cstplus-channel@YOUR_SLUG"
```

The restart seeks to the correct position immediately.

{% hint style="info" %}
This is a known limitation on some ffmpeg builds: the `-ss` seek on a `concat` + `stream_loop` input can accumulate a small drift over many hours. A restart corrects it instantly. The EPG itself is always correct.
{% endhint %}


---

# 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/channel-issues.md?ask=<question>&goal=<user_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.