Automated yt‐dlp Version Enforcement

Stopped Queue: huey_net_limited and Task will run immediately

Troubleshooting: Stuck Jobs and huey-net-limited Service Stoppage

This page helps you diagnose and resolve situations where TubeSync background tasks—such as playlist syncing, metadata fetching, and video downloading—are scheduled but never process.

---

Quick Summary

Symptoms

• Background jobs appear stuck in the dashboard queue indefinitely.
• Scheduled jobs process briefly only after restarting the container, then freeze again.
• Container logs show a graceful shutdown sequence (Received SIGINT) with no accompanying error messages or crashes.

Immediate Fix (Manual Override)

If you cannot update the container immediately, run this command to force the background download queue back online:

docker exec -it TubeSync /command/s6-rc -e start huey-net-limited

Note: Because of how the safety system functions, this service will remain active and process your queue until the container is recreated or deleted.

Permanent Fix (Zero-Downtime Safe Rolling Update)

To apply the updated image layers cleanly without risking your configuration, pull the new image, stop the active instance with an unlimited timeout (to allow active yt-dlp download sessions or database changes to complete cleanly), and rename it to TubeSync_previous. You can then inspect its configurations, create the replacement container, start it, and use a shell loop to verify its health status before removing the backup.

# 1. Pull the newest image layers from the registry
docker pull ghcr.io/meeb/tubesync:latest

# 2. Stop with unlimited timeout (-t -1) and rename your existing container to keep as an intact backup
docker stop -t -1 TubeSync
docker rename TubeSync TubeSync_previous

# 3. Read your original volume configurations directly from the previous container
docker inspect --format='{{range .Mounts}}-v {{.Source}}:{{.Destination}} {{end}}' TubeSync_previous

# 4. Read your original environment variables directly from the previous container
docker inspect --format='{{range .Config.Env}}-e "{{.}}" {{end}}' TubeSync_previous

# 5. Create the replacement container using the configuration details discovered above
docker create --name TubeSync \
  -v /your/discovered/config/path:/config \
  -v /your/discovered/downloads/path:/downloads \
  ghcr.io/meeb/tubesync:latest

# 6. Start the newly created container
docker start TubeSync

# 7. Wait automatically until the container reports a healthy status
echo "Waiting for TubeSync to pass health checks..."
until [ "$(docker inspect --format='{{.State.Health.Status}}' TubeSync)" = "healthy" ]; do
    sleep 2
done
echo "Container is healthy!"

# 8. Safely remove the previous backup instance now that the replacement is fully verified
docker rm TubeSync_previous

(If you use Docker Compose, running docker compose pull followed by docker compose up -d handles this image swap, config matching, and healthy service transitions automatically without manual inspection steps.)

---

Detailed Technical Overview

TubeSync includes an automated health check mechanism designed to prevent outdated downloading tools from making repetitive, failing connections to external services. When an embedded yt-dlp version mismatch is detected against the latest available release upstream, the container safely pauses the limited task queue.

1. Verifying the Queue State

TubeSync relies on an internal process supervisor to manage its background services. You can inspect the exact runtime status of the network-limited queue consumer by running:

docker exec -it TubeSync /command/s6-svstat /run/service/huey-net-limited

If the safety system has paused your queue due to outdated yt-dlp binaries, the command output will reveal a clean exit status:

down (exitcode 0) 1027 seconds, ready 1027 seconds

An exit code of 0 confirms the service did not crash due to an internal error, database failure, or file system permission issue. It was instructed to stop intentionally by the supervisor framework.

2. Inspecting the Health Check Lock Files

The automated update tracking occurs in the container's volatile shared memory. You can view these active state files using:

docker exec -it TubeSync ls -Al /dev/shm/.healthcheck/

When an update condition is met, the directory will look similar to this:

-rw-r--r-- 1 root root 10 Jun 15 21:31 v.088c72e6
-rw-r--r-- 1 root root  5 Jun 15 21:31 v.088c72e6.i
-rw-r--r-- 1 root root  1 Jun 15 21:32 v.088c72e6.l
-rw-r--r-- 1 root root 18 Jun 15 21:31 v.088c72e6.t

Understanding the Alphanumeric Suffix

The random string appended to the filenames (e.g., 088c72e6) is a unique session identifier. This suffix is dynamically generated based on your specific system boot parameters and container instance variables. Expect this identifier to be completely different on your own deployment.

How the Lock Operates

• v.[ID].l: This is the lock file. The health check script only sends a shutdown command to the huey-net-limited consumer service at the exact instant this file is created after discovering a newer version of yt-dlp is available.
• The Override Window: As long as this unique .l lock file remains in the directory, the health check script will not issue any additional shutdown commands. This architecture is intentional; it allows you to manually restart the service via the /command/s6-rc utility, and the queue will continue running and executing your yt-dlp downloads without being closed down again.

3. Reviewing Process Trees

To confirm that the task queue workers have successfully resumed operations after your manual override, you can audit all running processes inside the supervisor tree:

docker exec -it TubeSync /command/s6-ps -H -l

Look for the active djangohuey process assigned to the limited queue. A running, healthy queue worker will appear in the hierarchy directly under the huey-net-limited service like this:

root   28    0.08  0.00     228       0  -      S     21:30:00  01.06s  s6-supervise huey-net-limited
app   213    0.14  0.52  477492   85120  -      SslN  21:30:07  01.80s   \_ /usr/bin/python3 /app/manage.py djangohuey --queue limited

If the djangohuey --queue limited child process is missing under huey-net-limited, the queue is still inactive and requires either a manual service start command or a full image update.