Troubleshooting¶

This page maps common yt-text failures to the actual output strings the MCP server returns.

First Checks¶

Run these before debugging a client integration:

yt-text --version

Then confirm:

• the binary is on PATH, or your client config uses an absolute path
• your MCP config file is in the right location for your client
• you restarted the client after changing MCP config

If you only want a fast connectivity check, call get_metadata first. It is the lightest path through the system.

Common Failures¶

Error: invalid YouTube URL or video ID: ...¶

What it means:

• the input does not parse as a supported YouTube watch URL, short URL, or bare video ID

What to do:

• use a normal YouTube watch URL such as https://youtube.com/watch?v=dQw4w9WgXcQ
• avoid playlist-only URLs when you mean to target a single video

Error: source error: video is private or requires authentication¶

What it means:

• the video is not publicly accessible from an unauthenticated request

What to do:

• test with a public video first
• do not expect yt-text to bypass private-video access control

Error: source error: video is age-restricted¶

What it means:

• YouTube is blocking access to the video without an authenticated or age-verified session

What to do:

• validate the workflow against a public non-restricted video
• treat age-restricted videos as unsupported for the default path

Error: transcribe error: no captions available (timedtext returned empty; try building with --features po-token)¶

What it means:

• metadata and language discovery worked, but the actual caption fetch was blocked or returned empty
• this is the common BotGuard / proof-of-origin token case

What to do:

• build with --features po-token
• verify the BotGuard sidecar is available in that build
• keep using get_metadata and list_languages even if transcript fetches are blocked; those paths can still succeed

Error: source error: PoToken required but botguard sidecar not available¶

What it means:

• YouTube requested a proof-of-origin token and the running build does not have the BotGuard path available

What to do:

• rebuild with --features po-token
• use a non-PoToken-requiring video for baseline validation if you are still wiring the environment

Error: transcribe error: whisper feature not enabled¶

What it means:

• the fallback path reached local speech-to-text, but the running binary was not built with whisper support

What to do:

• rebuild with --features whisper
• remember that the first whisper run downloads the model and will be slower

Error: transcribe error: whisper inference failed: ...¶

What it means:

• the local audio-to-text path started but failed during decode, model setup, or inference

What to do:

• retry with a normal captioned video to separate caption-path issues from whisper-path issues
• confirm you built with --features whisper
• expect the first whisper run to do extra setup work

Behavior That Looks Like A Bug But Is Intentional¶

Requested language did not match returned language¶

yt-text does not hard-fail on a missing requested language. The fallback chain is:

1. Manual captions in the requested language
2. Auto-generated captions in the requested language
3. Manual captions in any language
4. Auto-generated captions in any language
5. Whisper fallback if enabled and audio is available

If strict language choice matters:

• call list_languages first
• inspect the language field in JSON transcript output
• do not assume lang=en guarantees an English result

Metadata and language listing work, but transcript fetch fails¶

This usually means:

• YouTube is allowing watch-page metadata access
• but the timedtext fetch path is blocked or empty

That is the classic signal to try the po-token feature.

MCP Client Issues¶

Client shows no yt-text tools¶

What to check:

• the client config file path is correct for that editor
• the server command points to a real executable
• the client was restarted after config changes

See Integrations for client-specific config locations.

Server starts but the client behaves strangely¶

yt-text is a stdio MCP server. stdout is reserved for protocol traffic.

What to do:

• do not wrap yt-text in a script that prints banner text to stdout
• keep any logging on stderr
• prefer calling the binary directly in MCP config