Troubleshooting¶

This page maps common tubebrain failures to the actual output strings the MCP server returns.

First Checks¶

Run these before debugging a client integration:

tubebrain --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: get_transcript_section requires at_s or a YouTube timestamp such as t=2449s¶

What it means:

• get_transcript_section could resolve the video URL but did not have a timestamp anchor for the section window

What to do:

• pass a URL with a YouTube timestamp, such as https://www.youtube.com/watch?v=Rzi7oFTzjac&t=2449s
• or pass at_s explicitly when the URL should stay untimestamped
• use before_s and after_s only when the default 120-second before / 600-second after window is too wide or too narrow

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 tubebrain 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 after fallback attempts)¶

What it means:

• metadata and language discovery worked, but the actual caption fetch was blocked or returned empty
• this is usually a BotGuard / proof-of-origin token case, a stale caption URL, or a video whose captions are unavailable to the default fetch path

What to do:

• build with --features po-token
• verify the BotGuard sidecar is available in that build
• retry with a fresh watch-page resolve; auto-caption URLs are refreshed from YouTube's Android VR player response when visitor data is available
• 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

Invalid live Whisper settings¶

Cause:

• TUBEBRAIN_WHISPER_MODEL was not one of tiny.en, base.en, or small.en
• TUBEBRAIN_LIVE_WHISPER_WINDOW_SECS was not an integer number of seconds
• TUBEBRAIN_LIVE_WHISPER_OVERLAP_SECS was greater than or equal to the window

Recovery:

• unset the variables to use the default base.en, 15-second window, and 5-second overlap
• use tiny.en for fast smoke validation and base.en for the default local posture
• keep live windows at or below 120 seconds

poll_stream returns health: "degraded" and last_error.source: "noop-audio-chunk-transcriber"¶

What it means:

• live audio ingestion started, but the running binary does not include a stream STT backend
• default builds can fetch stream audio but cannot convert live chunks to text

What to do:

• rebuild with --features whisper
• poll again after starting a new stream session with the Whisper-enabled binary
• expect the first Whisper-backed run to download the selected local model

Behavior That Looks Like A Bug But Is Intentional¶

Requested language did not match returned language¶

tubebrain 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 tubebrain 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¶

tubebrain is a stdio MCP server. stdout is reserved for protocol traffic.

What to do:

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