Skip to content
EN
Get API key
Browse documentation

Guides

Fix yt-dlp 403 Forbidden

Update nightly, reduce concurrency, check Deno, then test cookies and a healthy exit IP—in that order.

On this page

Try this first

  1. Update nightly. Upgrade the Python environment used by the failing worker.
  2. Reduce load. Pause parallel jobs on this IP; test one video and one fragment at a time.
  3. Check Deno. Confirm that the verbose log detects the runtime.
  4. Try valid cookies. For a small job, use a browser session that can play the source.
  5. Replace a rejected IP. Start a fresh extraction through a healthy host or proxy exit.
Update, then check the required runtime
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version
deno --version
One source, one low-load transfer
python -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"
Use your failing URL, then a short public video as a control. This audio-only probe avoids FFmpeg and saves a new timestamped filename for each attempt.

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.

Update the worker's Python environment
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__)"
If you use the official executable instead
yt-dlp --update-to nightly
yt-dlp --version
yt-dlp -U alone updates within the current channel. Use --update-to nightly to switch from stable.

Rebuild 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 loadFirst diagnostic setting
Concurrent video jobsOne active video for this exit IP; stop the rest of the queue temporarily.
Native fragment requests--concurrent-fragments 1.
aria2 or another external downloaderReturn to --downloader native. If aria2 is later restored, start with -x 1 -s 1 -j 1.
Media bandwidthTry --limit-rate 2M as a conservative test, then increase gradually.
Extraction and new downloadsUse --sleep-requests 2 and --sleep-interval 5 --max-sleep-interval 10.
Nested retriesKeep both job-level and downloader-level retry counts bounded; do not multiply them across workers.
Retest the required video stream at low load
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.

Check the worker dependencies
deno --version
python -m pip show yt-dlp yt-dlp-ejs
python -m yt_dlp --list-impersonate-targets
Check runtime detection and challenge solving
python -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.

Linux service with Deno outside PATH
python -m yt_dlp --ignore-config --js-runtimes "deno:/opt/deno/bin/deno" --impersonate="" \
  --verbose --simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Replace /opt/deno/bin/deno with the actual executable. On macOS or Windows, use that worker's absolute Deno path instead.

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.

4. Try valid cookies for a small job

Test one known-working session. Confirm that the browser can play the exact source, then try its cookies with the same command and route.

Use the working Firefox session
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
  -f ba -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" --cookies-from-browser firefox \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Use an exported session on a headless worker
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
  -f ba -o "diagnostics/%(id)s-%(epoch)s.%(ext)s" --cookies private/youtube-cookies.txt \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Use Netscape-format cookies. Keep the file private and writable for this job; for a read-only secret, make a per-job copy.

If cookies load but YouTube says they are no longer valid, replace the session rather than repeatedly passing the same file. For a few videos, maintaining a browser login can be practical. For a large public-video collection, finding and refreshing many browser sessions is not a dependable scaling strategy.

For bulk work, manage a pool of usable proxy exit IPs and rotate at job boundaries, with a low per-IP request budget. Keep account cookies for sources that actually require account access. An IP change does not grant access to a private or unavailable video.

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.

  1. Keep the source, nightly revision, Deno, cookies if needed, and format selector the same.
  2. Test one replacement exit IP with a fresh extraction and a real media transfer.
  3. Confirm the proxy actually changed its outbound IP. A new gateway hostname or credential can still lead to the same exit.
  4. Keep a sticky proxy session throughout extraction, token generation and media transfer.
  5. Remove or cool down the failing exit in your pool. Rotate to another healthy exit for a new job or a controlled retry.
Test a replacement proxy session
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"
Substitute a real sticky-session proxy privately. The verbose log can expose proxy credentials; redact it before sharing.
Compare direct host access when available
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"
This disables environment/configured proxies for the test. Skip it when the host cannot reach YouTube directly.
Compare the host's IPv4 route
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"
A working IPv4 route may differ from the failing IPv6 route. With a proxy, -4 does not necessarily select the proxy's outbound IP family.
ResultNext action
Same source succeeds on a new exit IPKeep that route and its low-load baseline. Quarantine the failing exit rather than retrying it for every video.
Changing proxy credentials has no effectCheck the actual egress IP and session policy; the proxy may still use the same exit.
Player works, media fails only through the proxyCheck googlevideo.com access and that media uses the same exit/session.
One source fails on every tested route; the control worksInvestigate 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.

Keep extraction and transfer in the same Python job
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"])
This is a direct local download; it needs no API key. Add your verified cookie/provider options only if the earlier tests require them.

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

The request sequence
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 locationInterpretation
Unable to download API page / Unable to download webpageAn extraction request was refused. Identify that host before treating it as a media-server failure.
unable to download video data: HTTP Error 403: ForbiddenThe selected media request was refused. Follow the solver/token/route branches below.
Fragment retry messagesA 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 inputFFmpeg 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 AccessDeniedThe 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.

Install the connector in yt-dlp's Python environment
python -m pip install "bgutil-ytdlp-pot-provider==2.0.2"

For yt-dlp running on the Docker host. Publish only the loopback port.

Start the provider
docker run --name bgutil-provider -d --init -p 127.0.0.1:4416:4416 brainicism/bgutil-ytdlp-pot-provider:2.0.2
Check the service from the downloader's environment
python -c "from urllib.request import urlopen; print(urlopen('http://127.0.0.1:4416/ping', timeout=5).status)"
Expect HTTP 200. Run this inside the worker container if that is where yt-dlp runs.
Request mweb media with the provider
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"
What to look for in the log
PO Token Providers: bgutil:http-2.0.2 (external)
Generating a gvs PO Token for mweb client via bgutil HTTP server
[download] 100%
These are shortened lines from our working local run. Provider discovery, token generation and media transfer are three separate checks.
Observed resultFix
PO Token Providers: noneThe 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 … /pingStart the provider or correct base_url. Check from the downloader process, not only your laptop browser.
Provider listed, but no generation happensRead 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 rejectionMove to session/network diagnosis. Generating a token does not authenticate the browser account.
mweb token works, old forced client still failsDo 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.

Use a provider on the worker's Docker network
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.

List the formats for this request context
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose --no-playlist \
  -F "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Test the failing ID from that list
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"
Replace YOUR_FORMAT_ID. For a merged selection, test the video and audio IDs separately. For a clip, first test an uncut stream.

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.

Apply pacing to your existing collection configuration
python -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf -t sleep --retries 3 \
  --fragment-retries 3 --batch-file urls.txt
Use the configuration that contains the now-working runtime, provider, output and archive options. The sleep preset spaces requests within this process; it does not coordinate other workers.

A 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.