Browse documentation
Guides
Update nightly, reduce concurrency, check Deno, then test cookies and a healthy exit IP—in that order.
On this page
Try this first
- Update nightly. Upgrade the Python environment used by the failing worker.
- Reduce load. Pause parallel jobs on this IP; test one video and one fragment at a time.
- Check Deno. Confirm that the verbose log detects the runtime.
- Try valid cookies. For a small job, use a browser session that can play the source.
- Replace a rejected IP. Start a fresh extraction through a healthy host or proxy exit.
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version
deno --versionpython -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
-f ba -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" --downloader native \
--concurrent-fragments 1 --limit-rate 2M --sleep-requests 2 \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Run on the failing worker. Check the verbose Proxy map for its actual route. --ignore-config removes saved options but keeps installed plugins and environment proxies.
Success means a saved file. Once audio works, test video with -f bv, then restore your full output settings. --simulate and -F do not test a media transfer. The 2M cap is a starting point for diagnosis.
1. Update to nightly
A previously working command suddenly fails: update first. YouTube player changes can break older extractors; the latest nightly may already contain the fix.
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version
python -c "import sys, yt_dlp; print(sys.executable); print(yt_dlp.__file__)"yt-dlp --update-to nightly
yt-dlp --versionRebuild and restart a container if its image contains an older package; updating Python on the host does not update that container. Keep the exact revision in the job log and run the same source again before changing other settings.
Remove old player_client, player_js_version and formats=missing_pot overrides for the baseline. A workaround from an old incident may now select an unsuitable client or expose a stream whose token is still missing. Issue #14680 is an example of a player change fixed upstream; copying its temporary override indefinitely is not the fix.
2. Reduce concurrent requests
Downloads work, then fail as volume rises: reduce the total load on the exit IP. In FlashData’s experience, fast parallel transfers can trigger rejection. Slow every worker sharing the route.
| Source of load | First diagnostic setting |
|---|---|
| Concurrent video jobs | One active video for this exit IP; stop the rest of the queue temporarily. |
| Native fragment requests | --concurrent-fragments 1. |
| aria2 or another external downloader | Return to --downloader native. If aria2 is later restored, start with -x 1 -s 1 -j 1. |
| Media bandwidth | Try --limit-rate 2M as a conservative test, then increase gradually. |
| Extraction and new downloads | Use --sleep-requests 2 and --sleep-interval 5 --max-sleep-interval 10. |
| Nested retries | Keep both job-level and downloader-level retry counts bounded; do not multiply them across workers. |
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
--downloader native --concurrent-fragments 1 --limit-rate 2M --sleep-requests 2 \
--sleep-interval 5 --max-sleep-interval 10 --retries 1 --fragment-retries 1 -f bv \
-o "diagnostics/%(id)s-%(epoch)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"If the low-load transfer works, keep that baseline and increase one dimension at a time while watching failures. If it still fails immediately after nightly/runtime checks, do not keep reducing bandwidth indefinitely: test a different exit IP. A route already flagged by YouTube may stay rejected after the traffic that triggered it has stopped.
3. Check Deno
Check both dependencies on the worker: Deno runs the challenges; yt-dlp-ejs supplies the solver scripts. The [default] extra installs the scripts. Install Deno separately.
deno --version
python -m pip show yt-dlp yt-dlp-ejs
python -m yt_dlp --list-impersonate-targetspython -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
--simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"Read the JS runtimes line for Deno, and any [jsc:deno] solving messages. A missing-runtime or signature/n-challenge warning needs fixing before another large download run. Deno 2.3+ is the current minimum in upstream EJS documentation; use an up-to-date supported version.
python -m yt_dlp --ignore-config --js-runtimes "deno:/opt/deno/bin/deno" --impersonate="" \
--verbose --simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"The curl-cffi extra enables --impersonate="". It provides browser-like request fingerprints; it does not replace Deno. If the browser target is unavailable, install the extra in the same Python environment. If impersonation introduces a failure on a working route, compare the identical request without the flag.
After the dependency check, rerun the real media transfer. If the current nightly still reports signature-solving failure for the same player, save the player ID and solver message for the matching upstream issue. If solving succeeds and the media gets 403, continue to the session/IP checks.
5. Replace a rejected exit IP
Same public video, same settings, different result by IP: replace the failing exit. FlashData sees many persistent 403s caused by poor or flagged proxy IPs. Reinstalling yt-dlp does not repair that route.
- Keep the source, nightly revision, Deno, cookies if needed, and format selector the same.
- Test one replacement exit IP with a fresh extraction and a real media transfer.
- Confirm the proxy actually changed its outbound IP. A new gateway hostname or credential can still lead to the same exit.
- Keep a sticky proxy session throughout extraction, token generation and media transfer.
- Remove or cool down the failing exit in your pool. Rotate to another healthy exit for a new job or a controlled retry.
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
-f ba -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" --proxy "http://USER:PASSWORD@HOST:PORT" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
-f ba -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" --proxy "" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
-f ba -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" \
--force-ipv4 "https://www.youtube.com/watch?v=jNQXAC9IVRw"| Result | Next action |
|---|---|
| Same source succeeds on a new exit IP | Keep that route and its low-load baseline. Quarantine the failing exit rather than retrying it for every video. |
| Changing proxy credentials has no effect | Check the actual egress IP and session policy; the proxy may still use the same exit. |
| Player works, media fails only through the proxy | Check googlevideo.com access and that media uses the same exit/session. |
| One source fails on every tested route; the control works | Investigate that source, format and live state. Do not label the whole proxy pool broken from one video. |
Advanced: keep extraction and transfer on one IP
A common application bug is extracting info['url'] on one machine, storing it in a queue, and downloading it later elsewhere. Signed media URLs expire and may depend on the original IP and request headers. A rotating proxy can create the same split even within one application.
Queue the YouTube video ID and desired output settings. Have the worker perform a fresh extraction and download together. If the worker uses a proxy, keep the same egress through player extraction, token generation and the media requests. Ask the proxy provider for a sticky session instead of rotating every HTTP request.
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
options = {
"js_runtimes": {"deno": {}},
"impersonate": ImpersonateTarget(),
"format": "ba",
"outtmpl": "diagnostics/%(id)s-%(epoch)s.%(ext)s",
"noplaylist": True,
"verbose": True,
# If required, configure one sticky proxy for the entire job:
# "proxy": "http://USER:PASSWORD@HOST:PORT",
}
with YoutubeDL(options) as downloader:
downloader.download(["https://www.youtube.com/watch?v=jNQXAC9IVRw"])If this succeeds while requests.get(saved_media_url) or a separate FFmpeg process fails, inspect that handoff: URL age, extractor-provided headers, cookies and actual egress. Keep media URLs out of durable job records. When retrying expired extraction results, request fresh URLs from the original video ID.
Advanced: identify the failing request
Watch page / player response
→ available streams and their signed URLs
→ googlevideo.com media bytes or fragments
→ local FFmpeg processing-F lists extracted formats; --simulate stops before saving media. Neither proves that the selected stream will return bytes. If the log reaches Downloading 1 format(s) and then fails with a media-data 403, changing the output filename or installing FFmpeg will not repair that HTTP request.
YouTube client profiles such as mweb and web_safari change which player response yt-dlp requests. Some responses need a signature or n-parameter transformation; some media requests also need a GVS proof-of-origin token. A PO token for the player request is not interchangeable with one for media delivery or subtitles.
| Log location | Interpretation |
|---|---|
Unable to download API page / Unable to download webpage | An extraction request was refused. Identify that host before treating it as a media-server failure. |
unable to download video data: HTTP Error 403: Forbidden | The selected media request was refused. Follow the solver/token/route branches below. |
| Fragment retry messages | A segmented stream failed. Keep the fragment error and protocol; compare another available format instead of retrying the same fragment indefinitely. |
| FFmpeg says HTTP 403 while reading an input | FFmpeg is fetching remote media, for example for a clip. Check the URL and network passed to FFmpeg; this is not a local codec error. |
Storage upload returns AccessDenied | The file reached your upload stage. Fix bucket access and retry that upload, not the YouTube download. |
Advanced: install a PO-token provider
Use this branch when the needed formats are skipped for a missing GVS token, or your configured token is rejected. Tokens are bound to a client/request context and can be bound to the video ID. A token copied for one video is not a reusable credential for an entire queue. Use a provider to generate the token for the current request.
The following setup uses bgutil 2.0.2. It has two parts: a Python plugin loaded by yt-dlp and a JavaScript service that generates tokens. Keep their versions aligned when upgrading. The examples below use a service reachable on the same host at port 4416.
python -m pip install "bgutil-ytdlp-pot-provider==2.0.2"For yt-dlp running on the Docker host. Publish only the loopback port.
docker run --name bgutil-provider -d --init -p 127.0.0.1:4416:4416 brainicism/bgutil-ytdlp-pot-provider:2.0.2Requires Git, Node 22+ and npm. Run the last command in a separate terminal and leave it running. If the folder already exists, use your existing checkout of the matching release.
git clone --depth 1 --branch 2.0.2 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git
cd bgutil-ytdlp-pot-provider/server
npm ci
npx tsc
node build/main.js --host 127.0.0.1 --port 4416python -c "from urllib.request import urlopen; print(urlopen('http://127.0.0.1:4416/ping', timeout=5).status)"python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
-f ba -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" \
--extractor-args "youtube:player_client=mweb" \
--extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:4416" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"PO Token Providers: bgutil:http-2.0.2 (external)
Generating a gvs PO Token for mweb client via bgutil HTTP server
[download] 100%| Observed result | Fix |
|---|---|
PO Token Providers: none | The plugin is not loaded. Install it with the same Python interpreter; remove --no-plugin-dirs. For standalone binaries, use the provider's documented plugin ZIP installation instead of pip into an unrelated environment. |
Error reaching GET … /ping | Start the provider or correct base_url. Check from the downloader process, not only your laptop browser. |
| Provider listed, but no generation happens | Read earlier player errors. LOGIN_REQUIRED can stop the request before the token stage. A loaded plugin does not prove that it was used. |
| A token is generated, then bot/sign-in rejection | Move to session/network diagnosis. Generating a token does not authenticate the browser account. |
| mweb token works, old forced client still fails | Do not reuse mweb's token for that other client. Let the provider handle the selected context, or return to the working client configuration. |
For two containers, 127.0.0.1 inside the worker points to the worker itself. Put both services on the same Docker network and use the provider's service name, for example http://bgutil-provider:4416. Do not expose the provider port publicly.
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
-f ba -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" \
--extractor-args "youtube:player_client=mweb" \
--extractor-args "youtubepot-bgutilhttp:base_url=http://bgutil-provider:4416" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Issue #17681 records a manual-token failure resolved by switching to a provider. It also contains a later recurrence: treat the working fix as evidence for that token failure, not proof that every later 403 has the same cause.
Advanced: one format, clip or live stream fails
List formats with the same cookies, provider and network options as the failing download. Run the failing format directly. If a different available format works, you have narrowed the failure to a delivery/client path; you have not established that every resolution or codec is broken.
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
-F "https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
-f YOUR_FORMAT_ID -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"SABR warnings concern the formats offered by a client. They are not the same as an n-challenge failure. If an old web override produces only unavailable/unsupported formats, remove the override or use the documented mweb/provider path. Do not add formats=missing_pot as a fix: it exposes formats without supplying their missing token.
Live, recently ended and ordinary uploaded videos can expose different manifests. Include that state when searching upstream. If a recently ended stream is still being processed, an alternate currently available format or a later extraction may be the useful next test; adding a global codec override to every worker is not.
Resume one worker
First repeat the failed source with the original required video/audio output. Then resume one worker using the existing manifest, archive and output policy. If all jobs share the same failing session or route, pause that queue rather than multiplying its failures.
python -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf -t sleep --retries 3 \
--fragment-retries 3 --batch-file urls.txtA 403 returned on every attempt needs a changed condition before retrying. Do not set infinite fragment retries or move failed IDs into the success archive. If media finished and only storage delivery failed, resume the upload of the saved file.
Still failing? Prepare a useful error report
- Capture the actual failing transfer with --verbose, not only a successful --simulate run.
- Keep the yt-dlp revision, runtime/EJS versions, loaded provider and the selected format/protocol.
- Include the warning before the error, whether a token was requested, and whether the failure occurred before or after media selection.
- Record the outcomes of the same source over IPv4/direct/proxy only for the comparisons you actually ran.
- Remove cookie contents, proxy credentials, signed URLs and tokens before sharing the log. Keep hostnames and error messages.
Search upstream using the specific preceding warning and your release. If a matching regression is still open, retain the failing item and use a confirmed working path while tracking that fix. A clean log that says only '403' is less useful than a short record showing which request and controlled change failed.