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 channel/playlist indexing, metadata fetching, and video downloading—are pending but never enter a running state.

---

Quick Summary

Symptoms

• Tasks appear stuck (in the Scheduled section) on the tasks page indefinitely.
• Scheduled tasks 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 other services stopping.

Immediate Fix (Manual Override)

If you cannot update the container immediately, run this command to force the queue consumer service 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 restarted.

Permanent Fix

To apply the updated image layers cleanly without risking your configuration, pull the new image, stop the active container instance with an unlimited timeout (to allow active yt-dlp tasks 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 [ "healthy" = "$(docker inspect --format='{{.State.Health.Status}}' TubeSync)" ]; 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 container swap and config matching automatically without manual inspection steps.)

---

Detailed Technical Overview

Why does this happen?

This behavior is an intentional design choice. The purpose is to protect unattended containers from repeatedly attempting to use an embedded yt-dlp dependency that is outdated.

When YouTube changes its layout or streaming signatures, outdated software may trigger download failures. Left unchecked, this automated looping behavior might lead to YouTube banning your IP address entirely. To safeguard your network infrastructure, TubeSync automatically stops the network-limited task queue consumer service when a version gap is identified.

Verifying the Queue Consumer Service State

TubeSync relies on an internal process supervisor to manage its services. You can inspect the exact runtime status of the network-limited queue consumer service 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 files, 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.

Inspecting the Health Check State 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 hexadecimal string appended to the v. prefixed 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 stop 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 stop 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 tasks without being stopped again.

Reviewing Process Tree

To confirm that the task queue workers have successfully resumed operations after your manual override, you can audit all running processes inside the process 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.