Skip to content

16. Troubleshooting Guide

Quick diagnostic guide to identify and resolve common issues with docker-rtmp-multistream.

16.1 Quick Diagnostics

Work through these checks in order. Stop at the first one that fails.

  1. Is the container running?

    docker compose ps -a relay

    If the status is not Up, see Container Won't Start.

  2. Can OBS connect? If OBS reports that it cannot connect, check whether the relay refused it:

    docker compose logs relay | grep "access forbidden"

    If there is output, see IP Authentication. If not, see Cannot Connect from OBS.

  3. Is each service enabled?

    docker compose logs relay | grep -E "service enabled|Skipping|ERROR"

    If a service shows Skipping or ERROR, see Service Not Enabled for Twitch or YouTube.

  4. Does the stream appear on each platform? If not, see Stream Not Appearing for Twitch or YouTube.

  5. Are archive files being written? If not, see Archive Not Recording.

16.2 Common Issues by Category

16.2.1 Connection Problems

Can't connect to the relay or container won't start.

Symptoms: - Container exits immediately - OBS shows "Failed to connect to server" - Port not accessible

→ Connection Issues Guide

16.2.2 Service-Specific Problems

Stream works but doesn't appear on specific platforms, or archive not recording.

Symptoms: - OBS shows streaming but nothing on Twitch/YouTube - Archive directory empty - Service configuration errors

→ Service Troubleshooting: Twitch | YouTube | Archive

16.3 General Debugging

16.3.1 View Container Logs

# All logs
docker compose logs relay

# Follow logs in real-time
docker compose logs -f relay

# Last 100 lines
docker compose logs --tail=100 relay

# Filter for errors
docker compose logs relay | grep -i error

16.3.2 Check Service Status

Verify which services are enabled:

docker compose logs relay | grep -E "service enabled|Skipping|ERROR"

Each enabled service prints one line, for example:

Twitch Non-Partner configuration complete, and service enabled.
YouTube configuration complete, and service enabled.
Archive configuration complete, and service enabled.

A service that is not configured prints a skip line instead, and the relay keeps running without it:

TWITCH_KEY is not set. Skipping Twitch configuration.
YOUTUBE_KEY is not set. Skipping YouTube configuration.
ARCHIVE_PATH is not set. Skipping Archive configuration.

An invalid value stops the container. An ERROR: line names the variable, followed by the script that stopped, for example:

ERROR: TWITCH_PARTNER must be TRUE or FALSE (case insensitive).
[!] pre-init.d - 90_configure_twitch.sh failed. Stopping container.

To fix it, see Invalid Environment Value.

16.3.3 Test Configuration Syntax

docker compose exec relay nginx -t

Should show: nginx: configuration file /etc/nginx/nginx.conf test is successful

16.3.4 Check Active Configuration

docker compose exec relay cat /etc/nginx/http.d/app.conf

Look for uncommented include directives for enabled services.

16.4 Getting Help

If you're still experiencing issues:

  1. Check existing issues: GitHub Issues

  2. Gather information. These commands replace your stream keys with REDACTED, but read both files before you share them:

    docker compose logs relay | sed -E 's#(live2|/app)/[A-Za-z0-9._:-]+#\1/REDACTED#g' > logs.txt
docker compose config | sed -E 's/(_KEY: ).*/\1REDACTED/' > config.txt
uname -a; docker --version

  3. Open a new issue with:

  4. Clear description of the problem
  5. Steps to reproduce
  6. logs.txt and config.txt
  7. System information

16.5 See Also