Troubleshooting

Common Issues & Solutions

Stream Won't Start

If a stream fails to start or immediately stops after starting:

Check source URL: Verify the URL is correct and accessible from your server
Verify protocol: Ensure you are using the correct protocol prefix (rtsp://, rtmp://, https://)
Firewall rules: Confirm outbound connections to the source are not blocked
Authentication: If the source requires credentials, ensure they are included in the URL
Source availability: Confirm the source is online and streaming

# Test source connectivity from your server
ffprobe -v quiet -print_format json -show_streams "rtsp://source-url"

# Test with timeout
curl -m 10 -I "https://source-url/stream.m3u8"

RTMP Connection Issues

If RTMP sources or restreaming destinations fail to connect:

Port 1935: Verify port 1935 is open in your firewall (both inbound and outbound)
Stream key: Double-check the stream key is correct and has not expired
Server URL format: Use rtmp://server:1935/live/stream-key format
Concurrent limits: Some platforms limit simultaneous RTMP connections

# Check if port 1935 is open
ss -tlnp | grep 1935

# Test RTMP connectivity
ffprobe -v error rtmp://your-server:1935/live/test

High CPU Usage

If your server CPU usage is consistently high:

Check transcoding load: Each transcoded stream consumes significant CPU
Switch to passthrough: Use passthrough mode for streams that do not need re-encoding (~1–2% CPU vs 15–50%)
Enable GPU acceleration: Offload encoding to an NVIDIA GPU with NVENC
Reduce quality: Lower the output resolution or bitrate
Reduce concurrent streams: Stay within your hardware limits

CPU Guidelines per Stream: Passthrough ~1–2% | 720p ~15–25% | 1080p ~30–50% | 4K ~80–100%. See the Transcoding guide for details.

Buffering / Quality Issues

If viewers experience buffering or poor quality:

Check server bandwidth: Ensure sufficient upload bandwidth for all concurrent viewers
Reduce output quality: Lower the bitrate or resolution to match available bandwidth
Check source stability: An unstable source causes output buffering — verify source bitrate is consistent
HLS segment length: Default 2–6 second segments; shorter segments reduce latency but increase overhead
CDN delivery: For large viewer counts, use a CDN to distribute the load

Audio/Video Sync Issues

If audio and video are out of sync:

Re-encode audio: Enable audio transcoding to AAC even in passthrough mode to fix timing
Check source timing: The source may have timing issues — test with VLC or ffprobe
Use -async 1: Add this as an extra FFmpeg parameter to force audio sync
Restart the stream: Sync issues sometimes accumulate over time; restarting can reset them

# Check source stream timing
ffprobe -v error -show_entries stream=codec_type,start_time,duration \
  -of default=noprint_wrappers=1 "rtsp://source-url"

SSL Certificate Problems

If HTTPS is not working or browsers show certificate warnings:

Let's Encrypt renewal: Certificates auto-renew every 60 days; check that the renewal cron is active
Custom certificates: Must be in PEM format with the full certificate chain
Port 443: Ensure port 443 is open and not used by another service
Certificate path: Verify the certificate file paths in your web server configuration

# Check certificate expiry
openssl x509 -enddate -noout -in /etc/letsencrypt/live/yourdomain/cert.pem

# Test SSL connection
openssl s_client -connect yourdomain:443 -servername yourdomain

# Force certificate renewal
certbot renew --force-renewal

Important: Let's Encrypt certificates expire after 90 days. The auto-renewal process runs at the 60-day mark. If renewal fails, your HTTPS streams will stop working.

Required Ports

Ensure the following ports are open in your server's firewall:

Port	Protocol	Purpose
80	TCP	HTTP web panel and HLS delivery
443	TCP	HTTPS secure web panel and HLS delivery
1935	TCP	RTMP ingest and restreaming
8000+	TCP	Radio/audio streaming ports

# Open required ports with firewalld
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=1935/tcp
firewall-cmd --permanent --add-port=8000-8100/tcp
firewall-cmd --reload

# Or with UFW (Ubuntu)
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 1935/tcp
ufw allow 8000:8100/tcp

Diagnostic Commands

Use these commands to diagnose issues on your server:

System Resources

# Check CPU and memory usage
top -bn1 | head -20

# Check disk space
df -h

# Check memory details
free -h

# Monitor real-time resource usage
htop

Network Diagnostics

# Check listening ports
ss -tlnp

# Test source URL connectivity
curl -m 10 -o /dev/null -w "%{http_code}" "https://source-url"

# Check bandwidth usage
iftop -i eth0

Log Locations

# StreamDev application logs
/var/log/streamdev/

# FFmpeg process logs
/var/log/streamdev/ffmpeg/

# Web server logs
/var/log/nginx/access.log
/var/log/nginx/error.log

Tip: When contacting support, include the output of the diagnostic commands above along with your StreamDev version and server OS. This helps resolve issues faster.

Storage Requirements

HLS streaming generates temporary segment files on disk. Plan your storage accordingly:

1080p at 6 Mbps: approximately 2.25 GB per hour per stream
720p at 3 Mbps: approximately 1.35 GB per hour per stream
480p at 1.5 Mbps: approximately 675 MB per hour per stream

Important: HLS segments are rotated automatically, so only a few minutes of segments are stored at any time. However, if you enable DVR/catchup recording, storage usage increases significantly. Monitor disk space regularly.

Concurrent Stream Limits

The number of concurrent streams depends on your encoding mode and server hardware. Typical limits on a modern 8-core server:

Mode	Concurrent Streams	CPU Usage
Passthrough	20–50 streams	Very Low (1–2% each)
720p Transcoding	4–8 streams	Moderate (15–25% each)
1080p Transcoding	2–4 streams	High (30–50% each)
4K Transcoding	1–2 streams	Very High (80–100% each)

Tip: Mix passthrough and transcoding to maximize your server capacity. Only transcode streams that truly need resolution or bitrate changes.

HLS Latency

HLS streaming introduces inherent latency due to its segment-based delivery method:

Typical latency: 10–30 seconds behind the live source
Segment duration: Default 2–6 seconds per segment (3 segments in playlist = 6–18 seconds minimum)
Encoding delay: Additional 2–5 seconds for transcoding
Network delivery: Variable based on viewer location and network conditions

Tip: HLS is designed for reliability and compatibility, not ultra-low latency. If you need sub-5-second latency, consider using SRT for transport between servers and HLS only for final viewer delivery.

Important: Reducing HLS segment size below 2 seconds may cause playback issues on some devices. Always test with your target audience's devices before changing segment settings in production.