Skip to main content

​
No audio on any stream endpoint

If listeners hear nothing or players fail to connect:
  1. Check that all containers are running: 
    docker compose ps
    All services should show Up. If a container is restarting, check its logs: 
    docker compose logs <service-name>
  2. Verify your studio encoder is connected. Open the Icecast admin panel at https://<host>/icecast-admin/ and confirm that source connections appear on the primary (/primary) or fallback (/secondary) mount.
  3. Confirm the emergency audio file exists at emergency-audio/fallback.mp3. If no studio source is connected and this file is missing, Liquidsoap has nothing to play.

​
Studio encoder cannot connect

If your encoder (BUTT, etc.) fails to connect on port 8010 or 8011:
  • Check the firewall. Ports 8010 and 8011 must be open for your studio IP. Run sudo ufw status and verify the rules, or re-run the firewall setup: 
    sudo ./setup-firewall.sh --studio-ip <your-studio-ip>
  • Verify the harbor password. The encoder password must match HARBOR_PASSWORD in your .env file.
  • Confirm the port and mount. Primary uses port 8010 with mount /primary. Fallback uses port 8011 with mount /secondary.
  • Check Liquidsoap logs for connection errors: 
    docker compose logs liquidsoap

​
Stream plays but no sound (silence)

If the stream connects but you hear dead air:
  • Check your encoder output. Make sure audio is being sent (not muted at the source).
  • Review silence detection settings. Liquidsoap triggers an alert when audio drops below SILENCE_THRESHOLD_DB (default -40 dB) for SILENCE_DURATION seconds (default 15). Check your analytics logs for silence events: 
    docker compose logs analytics
  • If the fallback chain activated, verify the emergency audio file is not silent or corrupt.

​
SSL certificate issues

​
Certificate fails to obtain

  • Make sure port 80 is open. Let’s Encrypt requires HTTP access for ACME challenges.
  • Verify LETSENCRYPT_EMAIL is set to a valid email address in your .env file.
  • If you hit rate limits, set LETSENCRYPT_STAGING=1 in .env to use staging certificates while testing.

​
Certificate renewal fails

Check certbot logs: 
docker compose logs certbot
Ensure the Nginx container is running, as certbot uses it for the ACME challenge. Restart the stack if needed: 
docker compose restart nginx certbot

​
HLS stream not working

If /hls/live.m3u8 returns a 404 or fails to play:
  • HLS segments are generated by Liquidsoap. Check that the Liquidsoap container is running and producing segments: 
    docker compose logs liquidsoap | grep -i hls
  • Verify Nginx serves the /hls/ path. The default configuration handles this automatically, but if you customized nginx.conf, confirm the HLS location block is present.
  • HLS requires a short buffer time before segments are available. Wait 10-15 seconds after starting the stream before testing.

​
Status panel not loading

If the dashboard at your status panel URL does not load:
  • Check the API backend. Verify it is running: 
    docker compose ps status-panel
docker compose logs status-panel
  • Check CORS settings. STATUS_PANEL_CORS_ORIGIN in .env must match your dashboard URL exactly, including https://.
  • Verify Appwrite credentials. Confirm APPWRITE_ENDPOINT, APPWRITE_PROJECT_ID, and APPWRITE_TEAM_ID are correct. Incorrect values prevent users from accessing the panel.

​
Alerts not sending

If you are not receiving Pushover notifications:
  • Verify PUSHOVER_USER_KEY and PUSHOVER_APP_TOKEN are set correctly in .env.
  • Alerts have a 5-minute cooldown. If you recently received an alert, the system suppresses the next one of the same type until the cooldown expires.
  • Check the analytics service logs: 
    docker compose logs analytics

​
PostHog events not appearing

If events are missing from your PostHog dashboard:
  • Confirm POSTHOG_API_KEY is set in .env. If it is empty, analytics are disabled.
  • Check that POSTHOG_HOST points to the correct PostHog instance.
  • The analytics service polls Icecast every POSTHOG_POLL_INTERVAL seconds (default 30). Allow at least one polling cycle before checking.
  • Review the analytics service logs for errors: 
    docker compose logs analytics

​
Containers keep restarting

If one or more containers are in a restart loop:
  1. Check the container logs for the failing service: 
    docker compose logs <service-name>
  2. Common causes:
    • Missing .env variables — ensure all required passwords and hostnames are set.
    • Port conflicts — another service on the host may already be using ports 80, 443, 8010, or 8011. Check with sudo ss -tlnp.
    • Missing emergency audio — Liquidsoap may fail if emergency-audio/fallback.mp3 does not exist. Place a valid MP3 file in that path.
    • Insufficient memory — the stack requires at least 1 GB of available RAM. Check usage with free -h.

​
Listeners hear glitches or dropouts

If the stream has intermittent audio issues:
  • Check server resources. High CPU or memory usage can cause encoding issues. Monitor with htop or docker stats.
  • Check your network. Packet loss between your studio and the server causes dropouts. Test with: 
    ping -c 100 <server-ip>
  • Lower the bitrate. If your upload bandwidth is limited, switch to a lower bitrate encoding profile in your studio encoder.
  • Check listener count. If you are near the ICECAST_MAX_LISTENERS limit (default 500), Icecast rejects new connections. Increase the value in .env if your server can handle more.

​
Icecast admin panel not accessible

If https://<host>/icecast-admin/ returns an error:
  • Verify the Nginx and Icecast containers are both running: 
    docker compose ps nginx icecast
  • Confirm your ICECAST_ADMIN_USER and ICECAST_ADMIN_PASSWORD are set in .env.
  • Check that SSL is working by visiting https://<host> directly. If SSL is broken, fix the certificate first.