Troubleshooting YouTube Age-Restricted Videos with Cookies in Agent-Reach

To access age-restricted YouTube videos in Agent-Reach, you must configure a browser cookie source using agent-reach configure youtube-cookies <browser>, ensure yt-dlp is installed, and have a JavaScript runtime (Node.js or Deno) available for authentication.

Agent-Reach is an open-source content extraction tool that reads YouTube videos—including age-restricted and member-only content—by leveraging yt-dlp with authenticated browser cookies. When a video requires age verification, the tool must present valid session credentials from a logged-in browser to bypass restrictions. This guide explains how to configure and troubleshoot the cookie-based authentication system based on the actual implementation in the Panniantong/Agent-Reach repository.

Prerequisites for YouTube Access

Before attempting to access restricted content, Agent-Reach verifies two critical dependencies in agent_reach/channels/youtube.py.

Verify yt-dlp Installation

The YouTubeChannel.check() method first probes yt-dlp --version. If the binary is missing, the channel is reported as off and the user is instructed to install it.

pip install yt-dlp

Install a JavaScript Runtime

YouTube features (including age-restriction bypass) require a JS runtime. The same check() routine looks for either node or deno using shutil.which(). If neither is found, you will receive a warning that a JS runtime must be installed.

Install Node.js:

brew install node

# or

apt install nodejs

Or install Deno:

brew install deno

Configuring Browser Cookies

Once prerequisites are met, you must specify which browser's cookie store to use for authentication.

Set the Cookie Source

The CLI command writes the browser value to the configuration key youtube_cookies_from in ~/.agent-reach/config.yaml. In agent_reach/cli.py (lines 1090–1095), the implementation sets this value:

elif args.key == "youtube-cookies":
    config.set("youtube_cookies_from", value)
    print(f"✅ YouTube cookie source configured: {value}")
    print("   yt-dlp will use cookies from this browser for age-restricted/member videos.")

Run the configuration command:

agent-reach configure youtube-cookies chrome

Replace chrome with firefox, safari, or another supported browser that you use to access YouTube.

How Cookie Injection Works

When processing a YouTube URL, YouTubeChannel.transcribe() (or read() in the base class) calls the yt-dlp wrapper. The utility function render_ytdlp_fix_command() in agent_reach/utils/paths.py builds the command with the --cookies-from-browser flag:

yt-dlp --dump-json --cookies-from-browser chrome https://www.youtube.com/watch?v=VIDEO_ID

This flag instructs yt-dlp to read session cookies directly from the specified browser's store, authenticating the request as a logged-in user.

Verification and Diagnostics

Run the built-in diagnostic tool to verify the entire chain:

agent-reach doctor

Expected output for a working configuration:

YouTube: ok, 可提取视频信息和字幕
  → JS runtime: node (found)
  → Cookies source: chrome (found)

If the cookie source is missing or the JS runtime is absent, the doctor displays a warn message with the exact fix command.

Common Issues and Solutions

Symptoms and resolutions based on the source code implementation:

yt-dlp: command not found

• Root cause: yt-dlp is not installed.
• Fix: Run pip install yt-dlp or install from source with pip install -e ..

warn: yt-dlp 已安装但缺少 JS runtime

• Root cause: No JavaScript runtime detected.
• Fix: Install Node.js (brew install node / apt install nodejs) or Deno (brew install deno), then rerun agent-reach doctor.

Cookie source configured but still receiving "age-restricted" errors

• Root cause: The browser was not running or the user was not logged into YouTube when the cookie was read.
• Fix: Close Chrome completely, restart it, log into YouTube, then run agent-reach doctor again.

Auth check failed (cookies might be wrong)

• Root cause: The cookie store does not contain a valid YouTube session.
• Fix: Ensure you are logged into YouTube in the configured browser, or manually export fresh cookies via the browser's developer tools.

yt-dlp: error: Unable to download webpage

• Root cause: The configuration key may be mis-typed or missing.
• Fix: Verify in ~/.agent-reach/config.yaml that the key is exactly youtube_cookies_from (not youtube_cookie_source or similar).

Manual Fallback Command

If automatic detection fails, use the diagnostic output to generate a manual command. The render_ytdlp_fix_command() helper in agent_reach/utils/paths.py suggests the exact syntax:

yt-dlp --cookies-from-browser chrome --no-check-certificate --no-warnings -j "https://www.youtube.com/watch?v=RESTRICTED_ID"

Copy and paste this command to test cookie authentication directly without the Agent-Reach wrapper.

Summary

• Agent-Reach requires yt-dlp, a JavaScript runtime (Node or Deno), and a configured browser cookie source to access age-restricted YouTube content.
• Use agent-reach configure youtube-cookies <browser> to set the cookie source, which writes the youtube_cookies_from key to ~/.agent-reach/config.yaml.
• The YouTubeChannel.check() method in youtube.py validates dependencies, while transcribe() injects the --cookies-from-browser flag via the utility helpers in paths.py.
• Run agent-reach doctor to verify the configuration and identify missing components with specific fix commands.

Frequently Asked Questions

Do I need to stay logged into YouTube in my browser?

Yes. Agent-Reach reads cookies from the browser's live cookie store at runtime. If you log out of YouTube in Chrome or Firefox, the session cookies become invalid, and age-restricted video requests will fail. Always ensure you are logged into YouTube in the configured browser before running Agent-Reach.

Can I use a cookie file instead of extracting from a browser?

While the primary method uses --cookies-from-browser, you can manually export cookies to a file and use yt-dlp's --cookies flag if the automatic extraction fails. Refer to the docs/cookie-export.md file in the repository for manual export instructions, though the browser source method is preferred for automation.

Why does Agent-Reach require a JavaScript runtime for YouTube?

YouTube's age-restriction bypass and certain player scripts require executing JavaScript to decode signatures or navigate consent pages. The YouTubeChannel.check() method in youtube.py specifically looks for node or deno because yt-dlp delegates some parsing tasks to a JS engine when handling complex YouTube pages.

What happens if I configure cookies but yt-dlp is missing?

The YouTubeChannel.check() function will report the channel as off and prompt you to install yt-dlp first. Agent-Reach cannot proceed with video extraction until the yt-dlp --version probe succeeds, regardless of cookie configuration.

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