Skip to content

19. Archive Troubleshooting

Troubleshooting issues specific to local stream archiving.

19.1 Common Issues

Issue Description
Archive Not Recording No files appearing in archive directory, recording not working
File Format Issues Archive files won't play or are corrupted
Files Not Named as Expected Archive filenames are unclear or unexpected
Archive Grows Too Large Disk filling up with old archives, storage management
Debug Logs How to check Archive-specific logs and error messages

19.2 Archive Not Recording

19.2.1 Symptoms

  • Stream works on Twitch/YouTube
  • No files appearing in archive directory

19.2.2 Possible Causes

19.2.2.1 1. Archive Not Enabled

Check: Look for archive configuration in logs:

docker compose logs relay | grep -i archive

Solution: Set ARCHIVE_PATH in env/relay.env: 

ARCHIVE_PATH=/archive

19.2.2.2 2. Permission Denied

Check: Look for permission errors:

docker compose logs relay | grep -i "permission\|denied"

Solution: Fix directory permissions on host: 

chown 100:101 ./stream_archive
chmod o+w ./stream_archive

Why these IDs? The nginx process runs as UID:GID 100:101 inside the container.

19.2.2.3 3. Volume Not Mounted

Check: Verify volume is mapped:

docker compose exec relay ls -la /archive

Solution: Add volume to docker-compose.yml: 

volumes:
  - ./stream_archive:/archive

Then restart: 

docker compose down
docker compose up

19.2.2.4 4. Disk Space

Check: Verify available space:

df -h ./stream_archive

Solution: Free up disk space or use a different directory with more space.

Estimate space needed: - 1080p60 @ 20 Mbps: ~9 GB per hour - 720p60 @ 6 Mbps: ~2.7 GB per hour - 720p30 @ 3 Mbps: ~1.35 GB per hour

19.3 File Format Issues

Issue: Archive files won't play or are corrupted

Check: Verify archive format:

grep ARCHIVE_SUFFIX env/relay.env

Solution: Use compatible format: 

ARCHIVE_SUFFIX=flv   # Most compatible with RTMP
# or
ARCHIVE_SUFFIX=mp4   # Better compatibility with players

Note: flv is most reliable for RTMP streams. mp4 requires stream to complete cleanly.

19.4 Files Not Named as Expected

Issue: Archive filenames are unclear

Current behavior: Files use timestamp-based naming.

Solution: Files are named automatically based on: - Stream name from OBS - Timestamp - Suffix from ARCHIVE_SUFFIX

Example: mystream_2025-10-21_143022.flv

19.5 Archive Grows Too Large

Issue: Disk filling up with old archives

Solution: Implement cleanup strategy:

# Manual cleanup of files older than 30 days
find ./stream_archive -name "*.flv" -mtime +30 -delete

# Or use logrotate/cron for automatic cleanup

19.6 Debug Logs

19.6.1 Enable Detailed Logging

For Archive-specific issues, check logs:

# Archive-specific logs
docker compose logs relay | grep -i archive

19.6.2 Common Log Messages

Success messages: 

Archive configured and enabled.

Error messages: 

ERROR: ARCHIVE_PATH is not set
WARNING: /archive is not writable

19.7 See Also