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

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 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.

Only when all checks pass does the channel report "ok" and allow subtitle extraction commands documented in 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:

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:

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

agent-reach install

Or manually edit the configuration:

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:

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

   agent-reach doctor

   Examine the YouTube block to identify which prerequisite fails.

2. Verify yt-dlp installation

   yt-dlp --version

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

3. Check for JavaScript runtime

   which node
   # or
   
   which deno

   If nothing returns, install Node.js or Deno.

4. Confirm configuration when using Node

   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:

   agent-reach install

5. Extract subtitles manually

   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:

   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 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 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 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.

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 for edge-case handling or open an issue on the Panniantong/Agent-Reach repository.

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