Troubleshooting guide
How to fix common yt-dlp errors
Most yt-dlp failures are not mysterious. They usually come down to one of a few buckets: outdated yt-dlp, missing ffmpeg, bad format assumptions, or a site requiring cookies or sign-in state.
Always try this first
yt-dlp -U
yt-dlp --versionA surprising amount of yt-dlp troubleshooting starts and ends with updating to the latest release.
HTTP Error 403: Forbidden
Update yt-dlp first. If that does not fix it, clear the cache and try cookies. Old extractor logic breaks often.
Sign in to confirm you're not a bot
YouTube's bot check. Pass cookies from a signed-in browser and avoid datacenter IPs and request bursts.
nsig extraction failed / throttled downloads
YouTube changed its player JavaScript. Update yt-dlp — the fix always ships as a new release.
Requested format is not available
Run `yt-dlp -F URL` and pick a format that actually exists now. Do not assume old format IDs still work.
ffmpeg not found
Install ffmpeg and verify it is available on PATH. yt-dlp relies on it for merges and audio conversion.
Sign in to confirm your age / cookies required
Use cookies from a signed-in browser session when the platform requires auth or age verification.
ExtractorError / unsupported site changes
Update yt-dlp first. A lot of breakages are upstream site changes that get patched in newer releases.
How to troubleshoot faster
Do not randomly rotate flags. Identify which bucket the failure belongs to first: update problem, auth problem, ffmpeg problem, or format problem. That alone removes a lot of wasted trial and error.
If it keeps breaking
Tired of fixing this every time a site changes?
Paste a link to see what a managed import API returns — the one that stays current so your workflow doesn't break.