
{/* banner prompt: A playful but polished 3D clay-render, matte materials in sage green, cream and terracotta, of a stylized detective magnifying glass hovering over a small padlock icon that is cracking open, with a tangled network cable looping around a proxy-server box in the background, soft studio shadows, simple background, 16:9. */}

`yt-dlp` gave us the least helpful error message it has: `HTTP Error 410: Gone`. The standard fix is `yt-dlp -U`. We ran it. Already on the latest stable release. The video was not, in fact, gone — but proving that took three separate bugs stacked on top of each other, and the last one had nothing to do with `yt-dlp` at all.

We were debugging a small local downloader tool — a browser extension that hands a page URL and cookies to `yt-dlp` on the user's own machine, optionally routed through a local HTTP proxy for geo-unblocking. One specific site started failing every time, on a URL that worked fine a week earlier.

## The first clue was buried in `-v`

The plain error told us nothing. Adding `-v` for verbose output surfaced a line that's easy to scroll past:

```
WARNING: [SiteExtractor] The extractor is attempting impersonation, but no
impersonate target is available. If you encounter errors, then see
https://github.com/yt-dlp/yt-dlp#impersonation for information on
installing the required dependencies
```

That's the real signal. A growing number of sites fingerprint the TLS handshake and HTTP/2 frame ordering of incoming requests to tell a real browser apart from a scripted client — even when every header looks identical. `yt-dlp` can spoof a browser's TLS fingerprint via an optional dependency, `curl_cffi`, which wraps `libcurl` with impersonation profiles for Chrome, Safari, Firefox and so on. Without it, some extractors still try the request, get rejected at the TLS layer, and the site's edge returns a generic `410` instead of anything that explains what actually happened. The video was fine. `yt-dlp` just didn't look enough like a browser to be allowed to ask.

## The version window nobody tells you about

The fix looked trivial:

```sh
python3 -m pip install curl_cffi
```

It installed cleanly — `curl_cffi-0.16.0`, the latest release. `yt-dlp` still refused to use it, and `--list-impersonate-targets` came back with every target marked `(unavailable)`. The debug line was the giveaway:

```
[debug] Optional libraries: ... curl_cffi-0.16.0 (unsupported) ...
```

`yt-dlp` doesn't just check that `curl_cffi` is importable — it pins a narrow set of versions it actually trusts, because `curl_cffi`'s impersonation API has changed shape across releases. Digging through the installed `yt-dlp` build (it ships as a zip-app; `python -m zipfile` opens it like any other zip) turned up the exact check:

```python
curl_cffi_version = tuple(map(int, re.split(r'[^\d]+', curl_cffi.__version__)[:3]))

if curl_cffi_version != (0, 5, 10) and not (0, 10) <= curl_cffi_version < (0, 16):
    curl_cffi._yt_dlp__version = f'{curl_cffi.__version__} (unsupported)'
    raise ImportError('Only curl_cffi versions 0.5.10 and 0.10.x through 0.15.x are supported')
```

Latest-and-greatest was one minor version too new. The fix was to pin below the ceiling:

```sh
python3 -m pip install "curl_cffi>=0.10,<0.16"
```

**Lesson:** when a library depends on another native-extension package for an optional feature, don't assume "latest" is "supported" — check for a version gate specifically on the feature you're trying to turn on, not just on whether the import succeeds.

## Collateral damage from `--force-reinstall`

The first install attempt used `--force-reinstall` to make sure the correct version actually took. It did — but it also silently upgraded packages that were already correctly pinned for something else entirely: `certifi`, `cffi`, `markdown-it-py`, and `pygments` all jumped to newer versions than another tool in the same shared Python environment required. `pip` said so plainly, right at the end of the install:

```
ERROR: pip's dependency resolver does not currently take into account all
the packages that are installed. This behaviour is the source of the
following dependency conflicts.
some-other-tool 2.15.0 requires certifi==2026.4.22, but you have
certifi 2026.7.22 which is incompatible.
some-other-tool 2.15.0 requires cffi==2.0.0, but you have cffi 2.1.1 ...
```

None of those four packages actually needed upgrading — `curl_cffi`'s own requirement (`cffi>=2.0.0`, `certifi>=2024.2.2`) was already satisfied by the versions in place. `--force-reinstall` doesn't just reinstall the package you named; it re-resolves and reinstalls its entire dependency subtree, and when it does that it grabs the latest version satisfying each constraint rather than leaving an already-satisfied pin alone. In a shared base environment with several unrelated tools installed, that's a quiet way to break something you weren't even looking at.

The fix was to pin those four straight back:

```sh
python3 -m pip install "certifi==2026.4.22" "cffi==2.0.0" \
  "markdown-it-py==4.0.0" "pygments==2.20.0"
```

**Lesson:** avoid `--force-reinstall` in a shared or base Python environment. If you need a specific version of one package, ask for exactly that (`pip install "pkg==x.y.z"`) rather than forcing a full dependency re-resolve you don't control.

## A new error, and a wrong theory

With the right `curl_cffi` version in place, the impersonation warning was gone — replaced by a new one, appearing on every single attempt:

```
SSLError: Failed to perform, curl: (35) TLS connect error:
error:00000000:invalid library (0):OPENSSL_internal:invalid library (0)
```

This looks exactly like a known class of `curl_cffi` bug: its bundled BoringSSL build can clash with another OpenSSL-family library already loaded in the same Python process — commonly `cryptography`, pulled in transitively by something unrelated like browser-cookie decryption support. The natural fix is isolation: a clean virtual environment with only `yt-dlp` and `curl_cffi`, nothing that could drag in a conflicting crypto library.

We built that environment. Same error, 100% reproducible, in complete isolation — no `cryptography`, no `secretstorage`, nothing else installed at all.

That result was more useful than a fix would have been. A clean-environment reproduction rules out an entire category of theories in one shot. It wasn't a Python packaging conflict. It had to be something outside Python's import graph.

## Stripping back to the dumbest possible test

The next step was to remove every layer of abstraction and test the actual thing that was failing: a TLS handshake over the proxy. Not `curl_cffi`. Not even `yt-dlp`. Plain, unimpersonated `requests`:

```python
import requests
r = requests.get("https://www.example.com",
                  proxies={"https": "http://127.0.0.1:8082"})
```

Same SSL error. Against a domain with nothing to do with the original site. That was the moment the whole investigation flipped: this was never a `curl_cffi` bug, or even a Python bug. Something about the proxy itself was breaking HTTPS.

Raw `curl` confirmed it in the plainest terms available:

```
* CONNECT tunnel established, response 200
> Client hello (1)
* OpenSSL SSL_connect: SSL_ERROR_SYSCALL in connection to www.example.com:443
```

The proxy's `CONNECT` tunnel came up cleanly — a `200 Connection Established` — and then the TLS handshake died immediately afterward, for every client, on every site. Nothing about `curl_cffi`'s TLS fingerprint mattered; the tunnel itself wasn't relaying bytes correctly once real TLS traffic started flowing through it.

The proxy client had several selectable exit gateways by region. Switching from one region to another and rerunning the exact same `curl` command fixed it instantly — clean `200`, valid response, every time. The original gateway node was in a broken state for HTTPS relaying specifically; nothing in our code, `yt-dlp`, or `curl_cffi` was ever going to fix that from the client side.

## What actually shipped

Three real problems, three real fixes, none of them where the first error message pointed:

<Table data={
    {
        headers: ['Symptom', 'Looked like', 'Actually was'],
        rows: [
            ['HTTP 410: Gone', 'Stale yt-dlp / dead video', 'Site requires TLS impersonation'],
            ['curl_cffi "(unsupported)"', 'Broken install', "Version above yt-dlp's pinned ceiling"],
            ['Unrelated tool broke after install', 'Unrelated bug', '--force-reinstall re-resolved shared deps'],
            ['SSL "invalid library" error', 'curl_cffi vs OpenSSL clash', 'Proxy gateway failing the TLS relay'],
        ]
    }
} />

The lasting fix was to isolate `curl_cffi`-enabled `yt-dlp` into its own virtual environment — so a future dependency bump anywhere else on the machine can never touch it again — and to symlink the `PATH`-resolved `yt-dlp` at that environment's build, so every caller picks it up without extra configuration.

## The general shape of this kind of bug

None of the individual fixes here are exotic. What made this one take longer than it should have was trusting each error message's own framing for too long:

- **"410 Gone" told us the video was gone.** It wasn't — it was an anti-bot response wearing the shape of a different error.
- **"unsupported" told us the install was broken.** It wasn't broken, it was one version too new for a pin we didn't know existed.
- **"invalid library" pointed straight at `curl_cffi` and OpenSSL.** It was neither — it was a proxy gateway with a bad TLS relay.

The pattern that actually broke each false lead was the same one every time: reproduce with the fewest possible moving parts. A clean virtual environment ruled out the packaging theory. Plain `requests` with no impersonation ruled out `curl_cffi` entirely. Raw `curl` against an unrelated domain ruled out the target site. Each step removed one whole category of suspects instead of guessing at the next fix — and the actual root cause, when it finally showed up, wasn't in any of the code we'd been staring at.


2cb8f8c42711684003baca7ec7f1abcaf8c1320b9f543ba32dd9702fcfc276ad

How we debugged a yt-dlp 410 Gone error that wasn't staleness: curl_cffi TLS impersonation, a strict version-pinning gotcha, a --force-reinstall dependency mishap in a shared Python environment, and a proxy gateway failure that mimicked a library bug.

A yt-dlp download kept failing with 'HTTP Error 410: Gone' even on the latest version. The real cause was three layered problems stacked on top of each other: missing TLS impersonation, a narrow curl_cffi version-compatibility window, and an unrelated proxy gateway fault that looked exactly like a library bug.

Debugging a Fake 410: yt-dlp, curl_cffi, and a Proxy That Lied


{/* banner prompt: A detailed, sunlit macro photograph of a miniature diorama on a wooden workbench: a tiny, stylized browser window is connected by a polished copper pipe to a small, intricate brass lockbox, symbolizing a private, local download, warm analog tones, shallow depth of field. --ar 16:9 */}

If you use [TYO Reach](https://reach.tyo.com.au), you already watch videos through your own
gateway, with your own logins. Sometimes you need the *file* — your own uploads,
a Creative Commons lecture, public-domain footage, a clip you have the rights to
keep. The usual answer is a "video downloader" website or extension, and the
usual price is your privacy: cloud converters see every URL you feed them, and
plenty of downloader extensions phone home with more than that.

**reach-dl** takes the other road. It is a small open-source extension that puts
a download manager in your browser's side panel — and keeps every byte of your
data on your machine.

## Private by architecture, not by promise

Most privacy claims are promises. reach-dl's is a design constraint: **there is
nothing to send your data to.**

When you queue a download, the extension collects the page URL and that site's
cookies, opens a local pipe to a tiny helper program on your own computer
(Chrome's native messaging — no network involved), and the helper runs
[yt-dlp](https://github.com/yt-dlp/yt-dlp) through your Reach proxy. The helper
exits when the download ends. There is no server, no message broker, no daemon,
no account, no telemetry. Your cookies go browser → local pipe → yt-dlp and are
written only to a temporary file that is deleted the moment the run finishes.
The download queue itself never touches disk and never contains cookies at all —
they are read fresh from the browser at the moment each download starts.

Because the download rides your Reach gateway with your browser's own
User-Agent and cookies, sites see the same session that just played the video —
which also keeps Cloudflare-protected sites happy where a bare command line
often fails.

## A real download manager, not just a button

Click the toolbar button on a video page (or right-click → **"Save with
reach-dl"**) and the side panel opens with the page queued:

![The reach-dl side panel with a download queue](https://storage.googleapis.com/www-tyolab-com-blog-assets/images/blog/2026/07/introducing-reach-dl-a-local-private-download-manager-for-tyo-reach/panel.png)
*The side panel: queue, progress, and per-item controls.*

- **Queue as many as you like** — downloads run one at a time (the Reach
  gateway is tuned for browsing, not bulk transfer) and process in order.
- **Pause and resume.** Pausing stops the download but keeps the partial
  `.part` file; resuming picks it up exactly where it left off. Even closing
  the browser mid-download loses nothing — re-add the URL and it continues
  from the `.part` file.
- **Honest errors.** When a download fails you see yt-dlp's *actual* error
  line and a link to the full local log — not a shrug. Most failures are just
  a stale yt-dlp (`yt-dlp -U`), and the panel says so.
- **Choose where files land.** A "Save to" field in the panel footer accepts
  any folder (`~/` works); leave it empty for `~/Downloads`. A typo'd folder
  fails loudly instead of saving somewhere surprising.
- **Through Reach, or direct — your call.** A "Download through TYO Reach"
  toggle (on by default) decides which network the download rides. Turn it
  off for videos that aren't geo-blocked: direct downloads skip the proxy,
  don't count against your Reach data allowance, and are usually faster. The
  choice is always explicit — reach-dl never silently switches your traffic
  from one network to the other.

![The panel footer: Reach toggle and Save-to field](https://storage.googleapis.com/www-tyolab-com-blog-assets/images/blog/2026/07/introducing-reach-dl-a-local-private-download-manager-for-tyo-reach/saveto.png)
*The footer settings — the Reach toggle (shown off: direct mode) and the Save-to field. The folder must already exist; reach-dl never creates or deletes anything on its own.*

Under the hood, "pause" is pleasingly boring: the extension simply disconnects
the local pipe; the helper notices and interrupts yt-dlp the same way Ctrl-C
would, which is exactly why the `.part` file survives. No state to sync, no
protocol to keep alive.

## Setup in three steps

reach-dl deliberately does **not** bundle yt-dlp — you install and update your
own copy, and the extension drives it.

```sh
# 1. install yt-dlp on your PATH (and keep it current: yt-dlp -U)
#    https://github.com/yt-dlp/yt-dlp#installation

# 2. load the extension: chrome://extensions → Developer mode →
#    "Load unpacked" → the ext/ folder from the repo; copy the extension ID

# 3. register the local helper (Go required):
git clone https://github.com/e-tang/reach-dl
cd reach-dl && ./install/install-host.sh <EXTENSION_ID>
```

Restart the browser, switch Reach on, and the toolbar button does the rest.
Everything is MIT-licensed at
[github.com/e-tang/reach-dl](https://github.com/e-tang/reach-dl) — the
extension, the Go helper, and the original one-line CLI wrapper it grew out of.

## The fine print, said plainly

reach-dl is for **legitimate saving**: your own uploads, openly licensed and
public-domain material, and uses your jurisdiction's copyright law actually
permits. Respect each site's terms. Downloads through Reach count against your
plan's data allowance — videos are big, so proxy only what is genuinely
geo-blocked and fetch the rest directly.

*Next up for reach-dl: quality and format selection before you queue. If you
try the extension, the repo's issues page is open.*


f91f90aa7baaf8c7f40f9e5d89ac19f7024634b2376a949f85af0d7f61fb07a3

reach-dl is an open-source browser extension that downloads videos locally through your TYO Reach proxy using yt-dlp — with a queue, pause/resume, and zero data leaving your machine.

reach-dl adds a side-panel download manager to your browser that saves the video you're watching — through your own TYO Reach gateway, with your own login, entirely on your own machine. No server, no cloud converter, no cookies leaving your computer.

Tag: Yt-dlp

Tag: Yt-dlp

Debugging a Fake 410: yt-dlp, curl_cffi, and a Proxy That Lied

Introducing reach-dl: a Local, Private Download Manager for TYO Reach