Troubleshooting

Common Issues

Database Connection Error

Problem: Application won't start with database connection error

Solution:

• Verify database host, username, and password are correct in environment variables

• Ensure MySQL/MariaDB is running and accessible

• Check network connectivity to database server

• Verify the database exists and is accessible to the specified user

• Database will be auto-created if it doesn't exist, but user must have CREATE privileges

No Files Being Encoded

Problem: Files are in watch folders but nothing is being encoded

Solution:

• For video: Ensure files are H.264 encoded and at least 720p resolution

• For audio: Ensure files are FLAC format only

• Check that watch folder paths are configured correctly in the Config page

• Verify the encoder has read permissions on the watch folder

• Check application logs for errors

• For H.265 files, a target resolution must be configured

• Verify watch folder paths exist on the system

Encoding Failures

Problem: Jobs fail with encoding error or produce corrupted output

Solution:

• Check that ffmpeg and ffprobe are available (included in Docker image)

• Verify input files are valid and not corrupted

• Ensure output directory has write permissions

• Check available disk space in temp directory and output location

• Verify file is not in use by another process

• Review job reports for specific error messages

• Check application logs: docker logs encoder

Watch Folder Marked as "Not Found"

Problem: Watch folder shows red status with "Not Found"

Solution:

• Verify the folder path exists on the system

• Check volume mounts in docker-compose.yaml if using Docker

• Ensure the encoder container has read access to the path

• If using Docker, paths must exist on the host system

Slow Encoding Speed

Problem: Encoding takes longer than expected

Solution:

• Reduce target resolution to lower value

• Adjust encoding preset to faster settings (in Config page)

• Increase CRF value (up to 28) for faster encoding with slightly less quality

• Check system resources: CPU usage, disk I/O, available memory

• Verify no other resource-intensive processes are running

• Check disk speed - encoding to slow storage will be bottlenecked by I/O

Permission Denied Errors

Problem: "Permission denied" errors when encoding

Solution:

• Ensure encoder process has read permissions on input files

• Ensure encoder process has write permissions on output directory and temp directory

• Check file ownership and permissions

• If using Docker, verify volume mounts have correct permissions

• Try running encoder with appropriate user/group permissions

Memory or Disk Space Issues

Problem: Encoding fails due to out of memory or disk space

Solution:

• Free up disk space (encoded files are typically smaller, but temp files need space)

• Reduce video resolution target to create smaller files

• Increase CRF value for faster encoding and smaller output

• Reduce preset speed if running out of memory

• Check available RAM - increase container memory limits if using Docker

Logs and Debugging

View application logs:

docker compose logs -f encoder

Access container shell:

docker compose exec encoder /bin/bash

Check database for job history:

SELECT id, encoder_type, file_path, status, created_at FROM job_reports ORDER BY created_at DESC LIMIT 20;

Check watch folder configurations:

SELECT * FROM encoder_config WHERE enabled = TRUE;

Check job queue:

SELECT * FROM job_queue ORDER BY created_at ASC;