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

> Troubleshoot YouTube age-restricted videos in Agent-Reach by configuring browser cookies, installing yt-dlp, and setting up a JavaScript runtime for authentication.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.

```bash
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:

```bash
brew install node

# or

apt install nodejs

```

Or install Deno:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1090–1095), the implementation sets this value:

```python
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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) builds the command with the `--cookies-from-browser` flag:

```bash
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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) suggests the exact syntax:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/youtube.py) validates dependencies, while `transcribe()` injects the `--cookies-from-browser` flag via the utility helpers in [`paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.