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

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, 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:

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:

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:

opencli bilibili subtitle BV1xx411

Install OpenCLI separately if your distribution requires it:

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:

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:

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 — Core channel implementation containing the yt-dlp removal comment and the read() method's 412 error handling and fallback logic.
• docs/README_en.md and README_ko.md — User documentation explaining the 412 block and recommending bilibili-cli installation.
• 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 — 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 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). 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}