yt-dlp errors explained: what each one means and the fix that works

By Tunelio team·Published Sep 7, 2026

Nearly every yt-dlp failure on YouTube has one of three roots: an outdated build, a missing JavaScript runtime, or an IP address YouTube distrusts. Run the three commands below first; they clear the majority of reports. Then find your exact error message in the catalogue — each entry gives the cause, the first thing to try, and the full guide for that error.

Universal first aid (do this before anything else)

yt-dlp -U                                   # or: pip install -U yt-dlp   (distro packages are months behind)
curl -fsSL https://deno.land/install.sh | sh  # JS runtime — required for YouTube since 2025
yt-dlp -4 --rm-cache-dir -vU "URL"             # IPv4, clean cache, verbose: see WHERE it fails

Read the -v output top to bottom: the debug header shows the version, the JS runtime and ffmpeg it found; the first WARNING or ERROR tells you which stage failed — the info request (YouTube would not describe the video), the media download (YouTube described it but refused the file), or post-processing (ffmpeg). The catalogue below is grouped that way.

Info-stage errors: YouTube will not talk to you

“Sign in to confirm you’re not a bot”

YouTube scored your request as automation — data-center or IPv6 address, no PO token, no session, too much volume. Fix order: update, JS runtime, -4, then cookies from a spare account in a private window, then a PO-token provider, then a residential exit. Cookies alone rarely last.

→ Full guide: fix “Sign in to confirm you’re not a bot”

“Unable to extract …”, “nsig extraction failed”, “Some formats may be missing”

YouTube changed its player code and your yt-dlp cannot solve the new signature, or there is no JavaScript runtime to run it. Update (nightly if stable is not out yet) and install Deno; remove the obsolete YTNsigDeno plugin if present. There is no flag that fixes this on an old build.

→ Full guide: how to update yt-dlp (pip, binary, brew, winget, nightly, Docker)

“Video unavailable”, “Private video”, “HTTP Error 404: Not Found”

The video is gone, private, region- or member-restricted — or the ID is mistyped. Check the URL in a browser: if it fails there too, nothing in yt-dlp helps. A 404 during download instead means a signed media URL expired (re-extract with -c); in playlists add --ignore-errors to skip dead entries.

→ Full guide: HTTP Error 404 causes and fixes

“Cookies are no longer valid”, “could not find … cookies database”, age-restricted / members-only

Session cookies rotate and expire; a jar exported from a browser you kept using is stale immediately, and cookies from your main account can get it restricted. Export once from a private window of a spare account, close it, pass --cookies cookies.txt. Age-gated and members-only videos need cookies from an account that can see them.

→ Full guide: export and use cookies safely

Media-stage errors: YouTube described the video but refuses the file

“HTTP Error 403: Forbidden” (often after the first chunk)

The signed media URL does not match the client, IP or PO token YouTube expected. Update and install a JS runtime, force IPv4, stop forcing itags with -f (use -S sorting), try another player client, provide a PO token; use cookies last — they can cause media 403s. Data-center and IPv6 addresses get this far more often.

→ Full guide: 403 Forbidden causes and fix order

“Requested format is not available”

The itag you forced does not exist for this video or is gated behind a PO token for your client. List formats with -F, then express a preference instead of an ID: -S "res:1080,ext:mp4". If 1080p+ is missing entirely, ffmpeg (for merging) or a PO token is the cause.

→ Full guide: ffmpeg, merging and why 1080p is missing

Very slow downloads (a few KB/s), stalls, throttling

Throttled speed is YouTube’s response to a wrong “n” parameter — almost always an outdated build or missing JS runtime, not your connection. Update first; then --concurrent-fragments 4 helps with fragmented formats. Rate-limiting on bulk runs is different: add sleep flags.

→ Full guide: updating yt-dlp

Proxy errors: “Unable to connect to proxy”, “Missing dependencies for SOCKS support”, bot check through a proxy

Check scheme and port (socks5h:// for remote DNS), install yt-dlp[default] for SOCKS, and remember the exit’s reputation is scored like your server’s — data-center proxies inherit the same 403s and bot checks; residential exits work but carry the whole video through them.

→ Full guide: proxies that actually work against YouTube

Post-processing errors: ffmpeg

“ffmpeg not found”, “You have requested merging … but ffmpeg is not installed”

Without ffmpeg yt-dlp quietly saves the best single-file format (usually 720p) and cannot make MP3s. Install it (apt/brew/winget), open a new terminal, or pass --ffmpeg-location. Check yt-dlp -v for the ffmpeg line.

→ Full guide: install ffmpeg and point yt-dlp at it

“Postprocessing: Conversion failed!”, output is .webm instead of .mp3

A corrupt partial download, a very old ffmpeg, or ffmpeg missing entirely. Delete the .part file, update both tools, retry with -x --audio-format mp3 --audio-quality 0 — or keep the original Opus/AAC with --audio-format best and skip the transcode.

→ Full guide: yt-dlp to MP3

→ Which to keep: WebM/Opus, M4A or MP3

Errors in code: DownloadError in Python, frozen async servers

yt-dlp wraps failures in yt_dlp.utils.DownloadError with the original message inside — match on the text (“Sign in to confirm”, “HTTP Error 403”, “Private video”). It is synchronous and costs ~1.2 s of CPU per extraction; called on an event loop it freezes the server — run it in a thread pool and cap concurrency.

→ Full guide: yt-dlp from Python

→ Putting yt-dlp behind an API: self-host vs hosted

Is it even safe / legal to run?

yt-dlp itself is open source and safe from the official releases or pip; antivirus flags on the Windows build are PyInstaller false positives. The risks are fake download sites, cookies from your main account and untrusted plugins. Legality depends on what you download and where you live.

→ Full guide: is yt-dlp safe?

Mistakes that turn one error into a permanent one

• Retrying a bot check or 403 in a tight loop — the fastest way to get an IP flagged for good.
• Passing your personal Google account’s cookies on a server.
• Forcing itags from old tutorials (-f 137+140) instead of -S sorting.
• Running a distro package from last year and reading forums instead of updating.
• Rotating cheap data-center proxies and expecting a different reputation.

When you should stop fixing yt-dlp

For a handful of personal downloads, the first-aid commands and the guides above will carry you. If yt-dlp runs inside a bot, an app or a pipeline, every error above becomes a recurring operations task — updates, runtimes, PO tokens, cookie rotation, residential proxies, ffmpeg CPU. A hosted API returns a download URL per request and keeps all of that server-side. Tunelio is our own service; weigh the pitch accordingly. New accounts get 100 free credits.

→ yt-dlp alternative: when a hosted API makes sense

Sources

• yt-dlp README and wiki — options reference, FAQ, PO token guide, cookies guide.
• yt-dlp issue tracker — #14680 and #17395 (403), bot-check and nsig threads.
• Our own measurements (Tunelio extraction fleet, 2026): challenge rates on data-center IPs, IPv6 refusals, CPU per extraction.