# How to Troubleshoot YouTube Subtitle Extraction Failures with yt-dlp in Agent Reach

> Troubleshoot YouTube subtitle extraction failures with yt-dlp in Agent Reach. Learn how to diagnose missing runtimes or config flags using the built-in check method.

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

---

**Agent Reach delegates YouTube subtitle extraction to yt-dlp, which requires a properly configured JavaScript runtime (Node.js or Deno) to parse YouTube's dynamic pages; missing runtimes or configuration flags cause extraction failures that can be diagnosed using the built-in `YouTubeChannel.check()` method.**

Agent Reach relies on **yt-dlp** to extract video metadata and subtitles from YouTube. Because YouTube serves dynamically generated JavaScript-heavy pages, yt-dlp needs a JavaScript runtime environment to execute parsing code. When this dependency is missing or misconfigured, subtitle extraction fails silently or returns errors. This guide walks through the diagnostic system implemented in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) to resolve these issues.

## Understanding the Root Cause

The `YouTubeChannel` class in [[`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) performs three critical validations before attempting extraction:

1. **yt-dlp binary presence** – Verifies the executable is accessible via `shutil.which("yt-dlp")`
2. **JavaScript runtime availability** – Checks for `deno` or `node` on the system PATH
3. **Node.js configuration** – Ensures yt-dlp's config includes `--js-runtimes node` when using Node.js (Deno works without extra configuration)

If any check fails, the system returns specific warning messages generated by the source code, guiding you toward the exact fix needed.

## Running the Built-in Health Check

Before troubleshooting manually, run Agent Reach's diagnostic command to identify which component is failing:

```bash
python -m agent_reach.cli doctor

```

Look for the YouTube channel status. If it reports `warn`, the output includes a specific message from `YouTubeChannel.check()` indicating whether the binary, runtime, or configuration is missing.

You can also invoke the check programmatically:

```python
from agent_reach.channels.youtube import YouTubeChannel

status, msg = YouTubeChannel().check()
print(f"Status: {status}")   # Returns: ok, warn, or off

print(msg)                   # Detailed guidance for fixing the issue

```

## Common Failure Scenarios and Solutions

### yt-dlp Binary Not Found

If the health check reports `yt-dlp: command not found`, the binary is not installed or not on your PATH.

**Fix:**

```bash
pip install yt-dlp

```

Verify installation with:

```bash
yt-dlp --version

```

### JavaScript Runtime Missing

When the error indicates a missing JS runtime (often displaying "缺少 JS runtime" or similar messages from the source), neither Node.js nor Deno is available on your system.

**Fix:**

Install either runtime:

- **Node.js**: `brew install node` (macOS), `apt install nodejs` (Ubuntu/Debian), or download from [nodejs.org](https://nodejs.org/)
- **Deno**: `brew install deno` or `curl -fsSL https://deno.land/x/install/install.sh | sh`

After installation, re-run `agent-reach install` to refresh the environment detection.

### Node.js Configuration Missing

When Node.js is installed but yt-dlp hasn't been configured to use it, you'll see a message indicating the runtime is present but not enabled. This occurs because yt-dlp requires the explicit flag `--js-runtimes node` when using Node.js (Deno requires no such configuration).

**Fix:**

Run the helper command generated by `render_ytdlp_fix_command()` in [[`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py). The command typically looks like:

```bash
mkdir -p '/home/you/.config/yt-dlp' && \
grep -qxF -- '--js-runtimes node' '/home/you/.config/yt-dlp/config' 2>/dev/null || \
printf '%s\n' '--js-runtimes node' >> '/home/you/.config/yt-dlp/config'

```

On Windows, this generates a PowerShell equivalent. This ensures the config file at `~/.config/yt-dlp/config` (or platform-specific path returned by `get_ytdlp_config_path()`) contains the required flag.

## Step-by-Step Troubleshooting Workflow

Follow this sequence to resolve subtitle extraction failures:

1. **Run diagnostics**
   
   ```bash
   python -m agent_reach.cli doctor
   ```

   
   Note the specific warning message for the YouTube channel.

2. **Verify yt-dlp installation**
   
   ```bash
   yt-dlp --version
   ```

   
   If this fails, install yt-dlp.

3. **Check JavaScript runtime**
   
   ```bash
   which node   # macOS/Linux

   where node   # Windows

   which deno   # Check for Deno alternative

   ```

   
   Install one if neither returns a path.

4. **Apply configuration fix (Node.js only)**
   
   If using Node.js, execute the command printed by the health check or run programmatically:
   
   ```python
   from agent_reach.utils.paths import render_ytdlp_fix_command
   import subprocess
   
   cmd = render_ytdlp_fix_command()
   subprocess.run(cmd, shell=True, check=True)
   ```

5. **Test subtitle extraction**
   
   ```bash
   yt-dlp --write-auto-sub --skip-download "https://www.youtube.com/watch?v=EXAMPLE"
   ```

   
   Look for `.vtt` or `.srt` files in your working directory. If successful, Agent Reach will now extract subtitles correctly.

## Programmatic Configuration Management

For automated deployments, use the utility functions from [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) to handle cross-platform configuration:

```python
from agent_reach.utils.paths import get_ytdlp_config_path, render_ytdlp_fix_command
from agent_reach.utils.text import safe_read_file

# Check current config content

config_path = get_ytdlp_config_path()
current_config = safe_read_file(config_path)

# Apply fix if needed

if '--js-runtimes node' not in current_config:
    fix_cmd = render_ytdlp_fix_command()
    # Execute the platform-specific command

    import subprocess
    subprocess.run(fix_cmd, shell=True)

```

This approach handles path differences between Windows (`%APPDATA%/yt-dlp/config`) and Unix systems (`~/.config/yt-dlp/config`) automatically.

## Summary

- **yt-dlp requires a JavaScript runtime** (Node.js or Deno) to parse modern YouTube pages and extract subtitles.
- **Agent Reach provides automated diagnostics** via `YouTubeChannel.check()` in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) that identify missing binaries, runtimes, or configuration flags.
- **Node.js requires explicit configuration** using the `--js-runtimes node` flag in yt-dlp's config file, while Deno works out-of-the-box.
- **Cross-platform fixes are available** through `render_ytdlp_fix_command()` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py), ensuring the correct configuration syntax for Windows, macOS, and Linux.
- **Always verify with `python -m agent_reach.cli doctor`** before manually editing configuration files.

## Frequently Asked Questions

### Why does yt-dlp need a JavaScript runtime for YouTube subtitles?

YouTube's modern interface relies heavily on JavaScript-generated content. According to the Agent Reach source code in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py), yt-dlp must execute this JavaScript to retrieve subtitle metadata and streaming data. Without Node.js or Deno available, yt-dlp cannot parse the dynamic page structure, resulting in extraction failures even when the video itself is accessible.

### Can I use Deno instead of Node.js for YouTube subtitle extraction?

Yes. The `YouTubeChannel.check()` method accepts either runtime. Deno works immediately after installation without additional configuration, whereas Node.js requires the `--js-runtimes node` flag in yt-dlp's configuration file. If both are installed, either will satisfy the validation check.

### Where is the yt-dlp configuration file located on Windows?

The `get_ytdlp_config_path()` function in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) resolves to `%APPDATA%/yt-dlp/config` on Windows systems. When using `render_ytdlp_fix_command()`, the utility generates a PowerShell-compatible command for Windows environments instead of the Unix-based commands used on macOS and Linux.

### How do I verify that subtitle extraction is working after applying fixes?

Run the standalone yt-dlp command to test subtitle retrieval without downloading the video:

```bash
yt-dlp --write-auto-sub --skip-download "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

```

If configured correctly, this creates a subtitle file (e.g., `dQw4w9WgXcQ.en.vtt`) in your current directory. Once this works, Agent Reach's YouTube channel will successfully extract subtitles during agent operations.