Blog/yt-dlp not working on YouTube: a ten-minute triage
OverviewAll posts
Troubleshooting

yt-dlp not working on YouTube: a ten-minute triage

Sort a failing yt-dlp command into one of five causes by reading the error line, then apply the matching check instead of guessing.

VTornado API team
Covered in this article
Read the error line first
Five causes and their checks
When the failures are structural
6 min reading time
Published November 14, 2026
VProduct guides by Velys Software

When yt-dlp stops working on YouTube, the error line already tells you which family of problem you have. Read it before changing anything. Most failures fall into five groups, and each has one check that confirms it.

Start with two commands

yt-dlp --version
yt-dlp -v "https://www.youtube.com/watch?v=VIDEO_ID"

Compare the version with the latest release. Then read the last ERROR: line of the verbose output and find it in the table.

Error line containsFamilyFirst check
HTTP Error 403: ForbiddenMedia request refusedUpdate, clear cache, download in one step
Sign in to confirm you're not a botAddress or volume challengedTry another network
Requested format is not availableFormat selectionList formats with -F
Video unavailable, Private video, members-onlyContent restrictionOpen the URL in a private browser window
Unable to extract, nsig extraction failedyt-dlp behind YouTubeUpdate to the latest or nightly release

The five families

1. yt-dlp is behind YouTube. Extraction errors that appear overnight on every video usually mean YouTube changed something. Update:

yt-dlp -U

If the latest stable release still fails, check the project's open issues and try the nightly channel with yt-dlp --update-to nightly. Recent releases also need a JavaScript runtime for full YouTube support; the verbose log says when one is missing.

2. The media request is refused. A 403 after formats were found has its own causes and checks, covered in yt-dlp 403 Forbidden.

3. The address or the volume is challenged. The sign-in message is a decision about your address, not about the video. See Sign in to confirm you're not a bot for what lasts and what does not.

4. The format selector asks for something that does not exist. List what is offered, then relax the selector:

yt-dlp -F URL
yt-dlp -f "bv*+ba/b" URL

A selector written for one video, with a fixed format code or a fixed container, fails on videos that do not offer it. Merging separate video and audio streams also requires FFmpeg on the machine.

5. The content is restricted. Private, removed, age-restricted, members-only and region-restricted videos fail whatever the tool. Confirm in a private browser window from the same country as your server. These are outcomes to record, not errors to retry.

Is it one failure or a pattern

A single failing video is a triage problem and the table above settles it. A failure rate is a different problem. If you run downloads in a backend, log the error family of every failure for a week. Two results are common:

  • Families 4 and 5 dominate. Your pipeline is healthy; improve format selection and handle restricted content as a normal result.
  • Families 1 to 3 dominate and grow with traffic. The failures come from operating downloads against YouTube at volume. Updates, addresses and sessions have become recurring work.

In the second case, compare the hours you spend on that work with the cost of handing the download step to a service.

Handing off the download step

Tornado API takes a source URL and returns a job. You follow the job to a final status and receive the file in your storage. Restricted content ends in a recorded outcome with its reason, and failed jobs are not billed. Over a 14-day window measured in October 2026, 236,054 jobs ran with 0 extraction failures.

Eligible new accounts get 100 GB free for 7 days. A useful test is to replay last week's failed URLs and compare. The migration guide lists what remains in your application afterwards: source selection, naming and everything downstream of the file.

Sources