Troubleshooting
Resolve the most common VidArch failures.
Port 2499 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.
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.