Troubleshooting

Find your symptom, read the likely cause, apply the fix. Start with the first tip: it solves most problems.

Always run the checker first

quikcast --config quikcast.toml --check

It reports the exact setting and file at fault, for example mounts[1].fallback: unknown fallback mount "/backup", and never starts the server. Secret contents are never printed.

The server will not start

Message or symptom	What to do
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.
retained audio budget cannot cover admission reservations	Your listener limits need more memory than the budget. 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.

My encoder cannot connect

Error	Cause
401 Unauthorized	Wrong username or password. The default username is source. Check for a newline or quotes in the secret file.
403 Forbidden	The mount has source_access rules and the encoder's address is not allowed. Behind a proxy, check trusted_proxies.
404 Not Found	There is no such mount. Paths are case-sensitive.
409 Conflict	Another encoder already owns the mount, or a relay does.
415 Unsupported Media Type	The encoder's content type is not supported. See the formats list.
Connection refused or timeout	Wrong host or port. listen = "127.0.0.1:8000" only accepts connections from the same machine.
Works directly but not through a proxy	See Encoders and proxies.

Listeners cannot play

Symptom	Cause and fix
404 for the stream	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 is draining or 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.
Everyone shows the same country or IP	You are behind a proxy. Configure trusted_proxies.

Relays

Symptom	What to check
Relay keeps reconnecting	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.
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.

HLS

Symptom	What to check
404 on the playlist	Both registration and publication are needed. After a restart everything is gone until your producer publishes again.
Browser blocked it	CORS. cors_origin must be the page's exact origin: scheme, host and port, with no trailing slash.
Upload 401	The HLS username or password is wrong, or you used a mount password (they must differ).
Upload 409	A stale generation or revision, a duplicate segment, or a window that skips ahead. Re-read the stream state, then continue.
Upload 503	HLS memory or upload slots are full. Raise allocation_budget, or publish a shorter window.

Reload problems

Symptom	What to check
Nothing changed after kill -HUP	Read the logs: a rejected reload says why and keeps the old config. Also check you edited the file Quikcast was started with.
"restart required"	You changed something that needs a restart: addresses, limits, the mount list or enabling TLS.

Still stuck?

1. Raise logging: QUIKCAST_LOG=quikcast=debug quikcast --config quikcast.toml.
2. Look at /api/stats and /api/mounts for what Quikcast believes is happening.
3. 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.