yt-dlp “HTTP Error 404: Not Found” — what it means and how to fix each cause

By Tunelio team·Published Sep 7, 2026

A 404 from yt-dlp means the thing it asked for does not exist at that address any more. Usually that is the video: deleted, made private, or a mistyped ID. Sometimes it is a media fragment whose signed URL expired, a playlist entry that was removed, or an outdated yt-dlp asking for an endpoint YouTube moved. Check the URL in a browser, update yt-dlp, and read the -v output — the section below tells you which case you have.

First, two commands

yt-dlp -U                       # an outdated build 404s on endpoints YouTube has moved
yt-dlp -vU --rm-cache-dir "URL"  # verbose: WHERE did the 404 happen — info page, API call, or media fragment?

Then open the same URL in a browser. If the browser also shows “Video unavailable”, no yt-dlp option will help; if the browser plays it, the cause is one of the technical ones below.

Cause 1: the video is gone, private or the ID is wrong

The most common 404. Videos get deleted by uploaders, removed for policy reasons, or switched to private or unlisted-with-restrictions. A video ID is exactly 11 characters (letters, digits, - and _); a copied URL with a trailing character, a missing character or tracking junk inside the ID gives a clean 404. yt-dlp usually reports these as “Video unavailable”, “This video has been removed” or “Private video” rather than a raw 404, but some paths surface the HTTP status directly.

# normalise the URL yourself: watch?v=ID, youtu.be/ID, shorts/ID all work
yt-dlp "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Private videos shared with your account need cookies from that account (see the cookies guide); age-restricted videos give a different error and also want cookies or another client.

Cause 2: the media URL expired (404 mid-download or on fragments)

The googlevideo URLs yt-dlp receives are signed and valid for roughly six hours. If a download is paused, resumed much later, or a script extracted the URL and used it hours afterwards, the media server answers 404 (or 403). Fragmented formats show this as “fragment N not found”. Re-run the extraction — yt-dlp -c resumes the file with fresh URLs.

yt-dlp -c --fragment-retries 10 --retries 5 "URL"

Cause 3: a playlist or channel contains removed items

yt-dlp --ignore-errors --download-archive done.txt "PLAYLIST_URL"

Playlists keep references to videos that no longer exist. Without --ignore-errors (-i) yt-dlp aborts the whole run at the first dead entry; with it, the entry is skipped and logged. --download-archive makes reruns incremental so you do not re-hit the same dead items every time.

Cause 4: outdated yt-dlp hitting a moved endpoint

YouTube changes internal API paths and player asset locations. A months-old yt-dlp can request a player JS file or an API route that no longer exists and report the resulting 404 as an extraction failure. This is fixed only by updating (see the update guide) — and check that the copy on your PATH is the one you updated.

Cause 5: region and account restrictions that surface as 404

Some region-blocked or members-only videos return “not available” pages that a few code paths report as 404. Try from another network or with a proxy (proxy guide) for region blocks; members-only content needs cookies from a subscribed account.

Symptom → cause

• Browser also says unavailable → deleted/private/wrong ID (cause 1). Nothing to fix on your side.
• Browser plays it; -v shows 404 on a player/API URL → outdated yt-dlp (cause 4).
• Download starts, then 404 on fragments or after a resume → expired signed URL (cause 2); re-extract with -c.
• Only some playlist items fail → removed entries (cause 3); add --ignore-errors.
• Fails only from the server, works at home → region/IP (cause 5) — or a 403 misread; see the 403 guide.

In a script or bot

Treat 404 as a permanent failure for that video (do not retry in a loop — retries do nothing for a deleted video and burn your IP reputation), log the video ID and the exact message, and move on. If you resolve URLs ahead of time, always re-resolve before downloading rather than caching signed links.

A hosted API does that classification for you: Tunelio (our own service) returns a clear 404 with a message for private or removed videos and refunds the request, so your bot can answer the user without parsing yt-dlp output. New accounts get 100 free credits.

Sources

• yt-dlp README — Download options (-c, --fragment-retries, --retries), --ignore-errors, --download-archive.
• yt-dlp wiki — FAQ on “Video unavailable” and outdated versions.
• yt-dlp issue tracker — 404 reports tied to expired fragment URLs and moved player assets.