Troubleshooting

Port 2508 is already in use

Stop the previous process or change the port published by Docker. In local development, also ensure that the 2498 API is free.

SQLite is read-only or downloads cannot be written

The published container runs as UID/GID 1000:1000. Grant that identity read/write access to both host directories mounted at /app/data and /app/downloads, then recreate the container. SQLite needs directory write access in addition to access to the database file because it creates -wal and -shm files. Follow the ownership or ACL commands in Storage; do not use chmod 777.

yt-dlp not found

Check the system page, PATH, and YT_DLP_PATH. With Docker, recreate the image or container rather than manually installing a non-persistent binary.

YouTube returns 403

Update yt-dlp, retry later, and add cookies only if necessary. Verify that the file matches the Netscape format and has not expired.

Download remains pending

Check running tasks, configured concurrency, logs, and disk space. Restart the service cleanly if the queue does not resume.

A local video will not play

Confirm that the file exists under DOWNLOADS_DIR, that the container can read it, and that the proxy forwards requests with byte ranges. Try directly via 127.0.0.1 to isolate the proxy.

The scanner finds nothing

It is suspended in local mode. Also check its activation, frequency, subscriptions, and logs from the last scan.

Connection refused after restore

Also restore .session_secret, or reconnect after generating a new secret. If AUTH_PASSWORD comes from the environment, its value must match the current configuration.