A player may fail to open a stream because Icecast is stopped, the source is missing, access is denied or the format is incompatible. Note the affected URL and the time. Then check the server, source and playback in that order.
Match the symptom to a first check
| Symptom | First checks |
|---|---|
| Process does not start | XML syntax, occupied socket, paths and runtime libraries |
| Status page works but mount is absent | Encoder output, source credentials, source limit |
| 401 or 403 | Intended account and mount authentication policy |
| 404 for a stream | Exact path, active source, alias/fallback target |
| Everyone hears interruptions | Source continuity and upstream delivery |
| One listener drops | Its network path, lag and slow-listener evidence |
| Garbled titles | Source charset and metadata update path |
Use error.log for server decisions and errors. access.log records requests and connections. The optional playlist log records metadata history, not a playable recording. Logs can include addresses, user agents and requested paths; restrict access and share redacted excerpts.
Enable a short diagnostic window
The 2.5.0 shipped example names log levels such as information and debug; older manuals use numeric levels. In an existing <logging> block, a temporary diagnostic change can be:
<loglevel>debug</loglevel>Reproduce one issue, record its time and restore the intended lower level. Debug output can grow quickly. Preserve the relevant startup messages, since they identify the running executable and configuration errors.
Set up log rotation
logsize and logarchive govern the documented internal rotation. Replacing one .old archive and retaining timestamped archives have different storage consequences. If an external rotation tool renames files, follow the installation’s supported reopen/reload mechanism; deleting an open file may not reclaim space as expected.
Back up a known-good configuration before diagnosis. Check XML with xmllint --noout --nonet, then check startup or reload logs. Change one setting at a time and keep the before/after observation. A quiet error log is not proof of good audio, so finish with actual source and player verification.