Skip to content

14. Troubleshooting Guide

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

14.1 Quick Diagnostics

Follow this flowchart to identify your issue:

Is the container running?
├─ NO → See [Connection Issues](connection-issues.md#container-wont-start)
└─ YES
   │
   Can you connect from OBS?
   ├─ NO → See [Connection Issues](connection-issues.md#cannot-connect-from-obs)
   └─ YES
      │
      Is the stream appearing on platforms?
      ├─ NO → See Service Issues: [Twitch](services/twitch.md#stream-not-appearing) | [YouTube](services/youtube.md#stream-not-appearing)
      └─ YES → Working correctly!

14.2 Common Issues by Category

14.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

14.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

14.3 General Debugging

14.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

14.3.2 Check Service Status

Verify which services are enabled:

docker compose logs relay | grep "configured and enabled"

Expected output: 

Twitch configured and enabled.
YouTube configured and enabled.

14.3.3 Test Configuration Syntax

docker compose exec relay nginx -t

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

14.3.4 Check Active Configuration

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

Look for uncommented include directives for enabled services.

14.4 Getting Help

If you're still experiencing issues:

  1. Check existing issues: GitHub Issues
  2. Gather information:
  3. Container logs: docker compose logs relay > logs.txt
  4. Environment: docker compose config > config.txt
  5. System info: uname -a; docker --version
  6. Open a new issue with:
  7. Clear description of the problem
  8. Steps to reproduce
  9. Logs and configuration (redact stream keys!)
  10. System information

14.5 See Also