Troubleshooting guide
YouTube downloads that stall and time out
The download starts, pulls a chunk, then freezes for several seconds, pulls the next chunk, freezes again — and eventually dies with Read timed out or X bytes read, Y more expected (where X + Y adds up to the chunk size). The request isn't being blocked — the bytes are being handed to you slowly. This is YouTube throttling the media stream, and it has its own set of fixes, separate from a 403 or a bot wall.
What you're actually seeing
[download] 31.2% of ~380.00MiB at 650.00KiB/s ETA 08:11
WARNING: Read timed out. Retrying (1/10)...
WARNING: [download] Got error: 9437184 bytes read, 1048576 more expectedYouTube serves the stream in chunks (often ~10MB) and paces how fast it releases each one. When a chunk comes too slowly, yt-dlp's socket read hits its timeout before the chunk finishes — that's Read timed out. When the connection drops mid-chunk, you get N bytes read, M more expected. It is not the same as a 429 / bot check (your request is allowed) or a missing-format error (you have the URL). The fix is to make the download survive the slow patches — and, where you can, shake off the throttle.
Fix 1: update first
How yt-dlp requests the stream, and which client it uses, changes constantly — and throttling is partly per-client. A current build is the cheapest fix:
yt-dlp -U
yt-dlp --update-to nightly # throttling workarounds often land here firstFix 2: let the download ride out the stalls
If a stall aborts the whole job, the real loss is that you gave up. Raise the socket timeout, retry forever, and resume instead of restarting:
yt-dlp \
--socket-timeout 30 \
--retries infinite \
--fragment-retries infinite \
--retry-sleep fragment:exp=1:20 \
--continue \
"https://www.youtube.com/watch?v=VIDEO_ID"--socket-timeout 30— wait longer before calling a slow read dead (default is shorter, so slow chunks trip it).--retries infinite/--fragment-retries infinite— keep retrying the HTTP request and each fragment instead of the default 10.--retry-sleep fragment:exp=1:20— exponential backoff between fragment retries (1s, 2s, 4s… capped at 20s), so you back off when YouTube is squeezing.--continue— resume the partial file; a fresh retry picks up where it stalled rather than re-downloading.
Fix 3: --throttled-rate to re-trigger extraction
This is the flag built for exactly this. --throttled-rate sets a minimumacceptable download rate. If the rate drops below it, yt-dlp assumes it's being throttled, re-extracts fresh stream URLs, and restarts the download — which often lands you on an un-throttled path:
yt-dlp --throttled-rate 100K \
--retries infinite --fragment-retries infinite --continue \
"https://www.youtube.com/watch?v=VIDEO_ID"Pick a floor well under your normal speed (e.g. 100K) so it only triggers on a genuine stall, not ordinary variance.
Fix 4: smaller chunks, and a different client
A smaller HTTP chunk size means each request is smaller, so a stall costs you less and sometimes sidesteps the per-chunk pacing:
yt-dlp --http-chunk-size 1M --continue "https://www.youtube.com/watch?v=VIDEO_ID"For DASH/HLS formats you can also pull fragments in parallel with -N 4 (--concurrent-fragments) — keep it modest, because hammering with many parallel requests is exactly what gets an IP flagged. And because throttling is partly per-client, switching the player client sometimes lands on a less throttled path — see choosing a YouTube player_client.
If it only crawls on a server
Here's the tell: the same command runs at full speed on your home connection but crawls or times out on an AWS/GCP/Hetzner box. None of the flags above change that, because YouTube throttles flagged datacenter IP ranges far harder than residential ones — it's the IP, not your config. See yt-dlp works locally but not on my server for what actually helps there.
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.