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

> Troubleshoot YouTube subtitle extraction issues with yt-dlp in Agent Reach. Learn to configure --js-runtimes for successful subtitle downloads.

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

---

**Agent Reach requires yt-dlp, a JavaScript runtime (Node.js or Deno), and proper `--js-runtimes` configuration to extract YouTube subtitles successfully.**

Agent Reach is an open-source platform routing layer that forwards requests to upstream tools like yt-dlp. When you troubleshoot YouTube subtitle extraction issues with yt-dlp in Agent Reach, you must verify three specific prerequisites before the channel allows subtitle commands to execute.

## Prerequisites Checked by the YouTube Channel

The YouTube channel implementation in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) validates three requirements through its `check()` routine before permitting subtitle extraction:

- **yt-dlp is installed and runnable** – The system executes `yt-dlp --version` via `probe_command`.
- **A JavaScript runtime is present** – Either `node` or `deno` must be available on `PATH`.
- **Node.js configuration includes `--js-runtimes`** – When using Node.js, the helper `_has_js_runtime_config()` searches for this flag in the user config file returned by `get_ytdlp_config_path()` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py).

Only when all checks pass does the channel report "ok" and allow subtitle extraction commands documented in [`docs/README_en.md`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/README_en.md).

## Common Failure Modes and Solutions

### yt-dlp Not Found

If `agent-reach doctor` reports `yt-dlp not found`, install the tool:

```bash
pip install yt-dlp

# or

uv tool install yt-dlp

```

### Missing JavaScript Runtime

The error "missing JS runtime" indicates neither Node.js nor Deno is on your `PATH`. Install one:

```bash

# Install Node.js

brew install node

# or

apt install nodejs

# Or install Deno

deno install

```

### Missing JS Runtime Configuration

When Node.js is present but the config lacks `--js-runtimes`, run the auto-fix command shown by `agent-reach doctor`, which internally calls `render_ytdlp_fix_command()` from [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py):

```bash
agent-reach install

```

Or manually edit the configuration:

```bash
mkdir -p ~/.config/yt-dlp
echo "--js-runtimes node" >> ~/.config/yt-dlp/config

```

### Empty Subtitle Output

If subtitles remain empty after configuration fixes, the video may lack subtitles or use incorrect language flags. Use explicit language options:

```bash
yt-dlp --write-sub --skip-download \
       --sub-lang "en,zh-Hans,zh-Hant" \
       -o "/tmp/%(id)s" "https://youtube.com/watch?v=VIDEO_ID"

```

## Step-by-Step Troubleshooting Workflow

Follow this sequence to diagnose and resolve extraction issues:

1. **Run the health check**

   ```bash
   agent-reach doctor
   ```

   Examine the YouTube block to identify which prerequisite fails.

2. **Verify yt-dlp installation**

   ```bash
   yt-dlp --version
   ```

   If this fails, reinstall: `pip install -U yt-dlp`.

3. **Check for JavaScript runtime**

   ```bash
   which node
   # or

   which deno
   ```

   If nothing returns, install Node.js or Deno.

4. **Confirm configuration when using Node**

   ```bash
   cat "$(python -c 'import agent_reach.utils.paths as p; print(p.get_ytdlp_config_path())')"
   ```

   Ensure the file contains `--js-runtimes`. If absent, run:

   ```bash
   agent-reach install
   ```

5. **Extract subtitles manually**

   ```bash
   yt-dlp --write-sub --write-auto-sub \
          --sub-lang "en,zh-Hans,zh,en" \
          --skip-download -o "/tmp/%(id)s" \
          "https://youtube.com/watch?v=abc123DEF"
   ```

6. **Optional: Use the transcribe helper**

   For audio transcription alongside subtitles, use [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py):

   ```python
   from agent_reach.transcribe import transcribe
   text = transcribe("https://youtube.com/watch?v=VIDEO_ID", provider="groq", config=my_config)
   print(text)
   ```

## Summary

- Agent Reach's YouTube channel in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) requires three validated prerequisites before allowing subtitle extraction.
- The `agent-reach doctor` command surfaces specific configuration gaps, including missing JavaScript runtimes or incorrect yt-dlp flags.
- You must install either Node.js or Deno, and when using Node.js, ensure `~/.config/yt-dlp/config` contains the `--js-runtimes` flag.
- 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) automates configuration repairs when you run `agent-reach install`.
- If subtitles remain empty after configuration, verify the target video actually contains subtitles in your requested languages.

## Frequently Asked Questions

### Why does Agent Reach need a JavaScript runtime for YouTube subtitles?

YouTube's subtitle extraction relies on yt-dlp, which requires a JavaScript runtime to execute certain extraction scripts and bypass anti-bot measures. The `check()` routine in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) explicitly verifies the presence of `node` or `deno` on your system `PATH` before permitting operations.

### How do I check if my yt-dlp configuration includes the `--js-runtimes` flag?

Run `cat "$(python -c 'import agent_reach.utils.paths as p; print(p.get_ytdlp_config_path())')" ` to view your configuration file. The file must contain the string `--js-runtimes`. Alternatively, run `agent-reach doctor` to automatically detect missing flags and display the rendered fix command from [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py).

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

Yes. The channel checks for either `node` or `deno` on your `PATH`. If you choose Deno, you typically do not need the `--js-runtimes` configuration flag required for Node.js installations, though you should verify with `agent-reach doctor` that the channel reports "ok".

### What should I do if subtitles are still empty after fixing the configuration?

First, confirm the video actually contains subtitles in your requested languages by checking on YouTube directly. Then use explicit language codes in your command: `yt-dlp --write-sub --sub-lang "en,zh-Hans"`. If issues persist, consult [`tests/test_channels.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_channels.py) for edge-case handling or open an issue on the Panniantong/Agent-Reach repository.