It reports the exact setting and file at fault, for example mounts[1].fallback: unknown fallback mount "/backup", without starting the server. Secrets are never printed.
failed to deserialize configuration ... (schema) with a line number
A setting is misspelled or has the wrong type (for example text where a number is expected). Unknown settings are rejected on purpose. Fix the line shown.
secret_file: failed to read ...
The path is wrong or unreadable. Paths are relative to the config file, not your current folder.
... exactly one of secret or secret_file
Set one, not both and not neither.
Address already in use
Another program (maybe a second Quikcast) uses that port. Stop it or change listen.
admin_listen rejected
It must be a loopback address such as 127.0.0.1:9090.
Your listener limits need more memory than the budget; the message says how much. Lower max_listeners or raise retained_audio_budget. See Capacity and limits.
logging stdout must be a pipe, socket, terminal...
You redirected output straight to a file. Use | tee file.log, systemd or Docker.
relay ... requires a unique configured local mount
A [[relays]]mount must match a [[mounts]]path exactly.
ip_allow_file ... contains no rules
An allow list file with no rules would admit everyone. Add an entry, or remove the setting.
No source is connected to the mount (or the path is misspelled). Quikcast does not serve silence. Start your encoder.
403 Forbidden
An access rule or a signed-link check refused the request. The response never says which, deliberately. Turn on quikcast=debug logging to see the reason.
403 only from your own computer
Testing from 127.0.0.1 against a country allow list: private addresses have no country and fail an allow list.
503
The server has stopped accepting connections (draining) or is full. Check max_listeners and listeners_per_mount, and /api/server.
Stream stops after a while
Listeners who cannot keep up are disconnected. Check slow_consumers_total. A slow connection or an underpowered proxy is the usual cause.
Works in VLC, not in the browser
The browser may not support the codec (Ogg and FLAC support varies). Try MP3 or AAC, or HLS.
GET /api/relays/<mount> shows the last error, status and next retry. Typical causes: wrong URL, bad credentials, an upstream format Quikcast does not accept, or a certificate problem.
destination_not_allowed
A public upstream redirected the relay (or an HLS playlist referenced a segment) to a private or local address, which is refused for safety. Fix the upstream, or point the relay at that address directly if it is yours.
Redirect error
The upstream redirects. Set max_redirects. HLS relays usually need max_redirects = 3, because segments are redirected to a CDN.
HLS relay is choppy, skips, or reconnects often
HLS relays are experimental. Try hls_variant = "lowest", set max_redirects = 3, or use the station's Icecast/SHOUTcast URL instead.
unsupported_or_invalid_media on an HLS upstream
The playlist is encrypted, uses byte ranges, carries video only, or holds FLAC/ALAC in MP4. Only AAC and MP3 audio is relayed.
HLS relay reconnects every few seconds
The playlist has ended (#EXT-X-ENDLIST), so it is not a live stream.
Stopped relay won't start
Editing enabled only takes effect after a reload (kill -HUP). Use POST /api/relays/<mount> to start it now.
Look at /api/stats and /api/mounts for what Quikcast believes is happening.
Report it to the Quikcast maintainers with your Quikcast version (quikcast --version), the redacted config, and the relevant log lines. Never paste passwords or tokens.