Troubleshooting guide
yt-dlp works locally but not on my server
The same command, the same yt-dlp version, the same URL: it downloads on your laptop and fails on your EC2 box, VPS, or Docker host. This is the most common yt-dlp support question right now, and the cause is almost never a bug. It's where the request comes from.
The one-line diagnosis
YouTube and most large sites score requests by IP reputation. Home and mobile IPs look like people; AWS, GCP, Azure, Hetzner, OVH, and most VPS ranges look like bots and get treated as hostile by default. Your laptop passes the same checks your server fails — not because yt-dlp behaves differently, but because the IPis different. Updating yt-dlp will not change your server's IP reputation.
This is actively confirmed by maintainers in current reports — see yt-dlp issues #17989 ("403 error even with deno (again)", opened Nov 3, 2026) and #18004 (Nov 6, 2026), where a maintainer calls the fragment 403s "classic IP blocking" unrelated to cookies or player changes.
Symptoms that point at the IP, not yt-dlp
- •
HTTP Error 403: Forbidden. Retrying fragment— downloads start, then die mid-file - •
Sign in to confirm you're not a boton a box that never signs in - • works for a few hours or days after setup, then stops — the IP got flagged
- • heavy throttling: a download that's instant locally crawls on the server
- • fails on a cloud host even with a current yt-dlp and a JavaScript runtime installed
If instead you see No supported JavaScript runtime could be foundor missing high-res formats, that's a different, fixable problem — see the JavaScript runtime guide.
Confirm it in 30 seconds
Run the same metadata-only probe in both places. It's cheap (no download) and isolates IP reputation from everything else:
yt-dlp --simulate -F "https://www.youtube.com/watch?v=jNQXAC9IVRw"If this lists formats on your laptop but 403s or returns "no formats" on the server with the same yt-dlp version (check yt-dlp --version on both), the difference is the IP. Nothing you pass to yt-dlp will fully fix a burned datacenter IP.
What actually helps (honest order)
- 1. Run it where the IP is clean. The simplest fix is to run the download on a residential or mobile connection (your own machine, a home server, a Raspberry Pi) and ship the file to the server afterward. Unglamorous, but it sidesteps the whole problem.
- 2. Route through a residential/ISP proxy.
--proxythrough a residential proxy makes the request look like a person again. It works, at real per-GB cost and added flakiness:
Datacenter proxies usually don't help — they're the same category of IP that's already blocked.yt-dlp --proxy "http://user:pass@residential-proxy:port" "URL" - 3. Pass cookies from a logged-in account. Export a
cookies.txton your local machine and use it on the server with--cookies. This raises your trust score but ties the activity to that account — never use one you care about, because automation from a datacenter IP is exactly what gets accounts flagged. Full steps in the cookies guide. - 4. Try a different player client — but test it. Some reports clear 403s by switching clients, e.g.
--extractor-args "youtube:player_client=web_safari". This is hit-or-miss: on a flagged IP it can return no formats at all, so verify it against your target before relying on it. It's a workaround for which client YouTube is least suspicious of, not a fix for the IP. - 5. Slow down.
--sleep-requests 2and limiting concurrency extends how long an IP stays usable before it's flagged.
What doesn't help
- • Updating again. Worth doing once to rule out a stale build, but a current yt-dlp won't change your IP's reputation. See updating yt-dlp.
- • A datacenter VPN or datacenter proxy. Same IP category as the server — often already burned.
- • Serverless (Lambda, Cloud Functions). The worst case: shared IP pools other people already burned, plus ffmpeg packaging and timeout pain.
Servers & agents
Works on your laptop but not on the server?
Paste a link to see what a hosted API returns from a clean residential IP — no cookies, proxies, or runtime to maintain on the box.