# What Causes the yt-dlp 412 Error for Bilibili and How to Work Around It

> Troubleshoot the Bilibili yt-dlp 412 error caused by risk-control filters. Learn how Agent-Reach uses bilibili-cli and OpenCLI to successfully download videos and subtitles.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-15

---

**Bilibili's risk-control filters return HTTP 412 "Precondition Failed" responses to yt-dlp requests, which Agent-Reach circumvents by replacing yt-dlp with bilibili-cli for metadata and OpenCLI for subtitles.**

The `yt-dlp 412 error` for Bilibili prevents video downloads when the platform detects automated request patterns from yt-dlp's YouTube-style backend. In the Agent-Reach repository, this server-side block forced a migration to dedicated CLI tools that interface directly with Bilibili's public API, eliminating the 412 precondition failures entirely.

## Understanding the yt-dlp 412 Error

Bilibili's server-side "risk-control" (4I2) filter identifies and blocks requests originating from yt-dlp's implementation. When `yt-dlp` attempts to fetch video streams or subtitles through its generic backend, Bilibili returns an HTTP 412 *Precondition Failed* response, effectively terminating the connection.

In [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py), the first comment documents the removal of `yt-dlp` support as of mid-2026. The channel's `read()` method previously relied on yt-dlp as a fallback, but now catches the 412 error explicitly, logs the detection, and immediately disables the yt-dlp path to prevent repeated failures.

## The Agent-Reach Workaround

Agent-Reach replaced the yt-dlp dependency with a two-tool approach: **bilibili-cli** handles video search and metadata retrieval, while **OpenCLI** manages subtitle extraction. This architecture bypasses the blocked YouTube-style backend entirely.

### Install the Dedicated Bilibili CLI

The `bilibili-cli` package provides direct access to Bilibili's public API for read-only operations. Install it using `pipx` or `uv`:

```bash
pipx install bilibili-cli

# or

uv tool install bilibili-cli

```

### Fetch Video Metadata and Search

Once installed, use the `bili` command to search videos and retrieve metadata without triggering the 412 filter:

```bash
bili search "YOUR QUERY"
bili info BV1xx411

```

These commands query `https://api.bilibili.com/` endpoints directly, avoiding the request patterns that activate Bilibili's risk controls.

### Extract Subtitles with OpenCLI

Subtitles are no longer fetched through yt-dlp. Instead, Agent-Reach delegates to OpenCLI, which extracts subtitle data via Bilibili's dedicated subtitle endpoint:

```bash
opencli bilibili subtitle BV1xx411

```

Install OpenCLI separately if your distribution requires it:

```bash
pipx install opencli

```

### Legacy Fallback Handling

The `BilibiliChannel` class retains a stub that attempts yt-dlp first for backward compatibility, but aborts immediately upon receiving a 412 response. This automatic switch requires no configuration changes—when the error is detected, the system transparently routes to the CLI-based flow.

## Implementation Examples

Use the Agent-Reach CLI to read Bilibili videos, which automatically routes through the new architecture:

```bash
agent-reach read "https://www.bilibili.com/video/BV1d4411N7zD"

```

Internally, this executes:

1. Search API queries via `bili-cli`
2. Subtitle extraction via `opencli bilibili subtitle BV1d4411N7zD`
3. yt-dlp 412 detection and suppression (if present)

Programmatically access the channel in Python:

```python
from agent_reach.channels.bilibili import BilibiliChannel

chan = BilibiliChannel()
metadata = chan.read("https://www.bilibili.com/video/BV1d4411N7zD")
print(metadata["title"])

# Subtitles populate automatically under metadata["subtitle"]

```

## Key Source Files and References

The following files in the Agent-Reach repository contain the implementation details and documentation:

- **[`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py)** — Core channel implementation containing the yt-dlp removal comment and the `read()` method's 412 error handling and fallback logic.
- **[`docs/README_en.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/README_en.md) and [`README_ko.md`](https://github.com/Panniantong/Agent-Reach/blob/main/README_ko.md)** — User documentation explaining the 412 block and recommending `bilibili-cli` installation.
- **[`tests/test_channels.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channels.py)** — Test suite asserting the `bilibili-cli` install command and verifying that yt-dlp is no longer a required dependency.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** — CLI helper functions that install `bilibili-cli` instead of `yt-dlp` for new setups.

## Summary

- **Root cause**: Bilibili's risk-control filters detect yt-dlp's request signatures and return HTTP 412 Precondition Failed responses.
- **Primary fix**: Agent-Reach removed yt-dlp dependency in favor of `bilibili-cli` for video metadata and OpenCLI for subtitles.
- **Implementation**: The `BilibiliChannel.read()` method in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) automatically catches 412 errors and switches to the CLI-based flow.
- **Installation**: Users must install `bilibili-cli` (and optionally `opencli`) via `pipx` or `uv` to restore full functionality.
- **Backward compatibility**: Legacy yt-dlp code remains but aborts immediately on 412 errors, ensuring seamless transitions.

## Frequently Asked Questions

### What exactly triggers the yt-dlp 412 error on Bilibili?

Bilibili's server-side "risk-control" (4I2) system monitors for specific request patterns associated with yt-dlp's YouTube-style backend implementation. When these patterns are detected, the server returns HTTP 412 Precondition Failed to block automated access, preventing video stream and subtitle retrieval.

### Why did Agent-Reach switch from yt-dlp to bilibili-cli?

The switch occurred because Bilibili began systematically blocking yt-dlp requests in mid-2026, making the tool non-functional for the platform. The `bilibili-cli` package communicates directly with Bilibili's public API using request signatures that comply with the platform's risk controls, ensuring reliable access to video metadata and search functionality.

### How do I install the required CLI tools for Bilibili support?

Install `bilibili-cli` for video search and metadata using `pipx install bilibili-cli` or `uv tool install bilibili-cli`. For subtitle extraction, install OpenCLI with `pipx install opencli`. These tools replace yt-dlp's functionality while avoiding the 412 error triggers.

### Can I still use yt-dlp with Agent-Reach for other sites?

Yes. The 412 error handling and removal of yt-dlp support applies specifically to the Bilibili channel ([`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py)). Other channels in the Agent-Reach repository continue to use yt-dlp where appropriate, as the Bilibili-specific risk controls do not affect other platforms.