Troubleshooting

The MCP server doesn’t start

Check that the package is installed globally:

npm ls -g video-context-mcp-server

If it’s missing, install it:

npm install -g video-context-mcp-server

Check that Node.js 20+ is installed:

node --version

VS Code: Make sure your .vscode/mcp.json is valid JSON and the command field is video-context-mcp. The shorter vmcp alias is available for CLI/cache commands, but video-context-mcp is the config value shown in the setup docs.

”No API key configured” error

The server needs at least one video API key. Check that the env block in your MCP config file contains at least one of: Z_AI_API_KEY, GEMINI_API_KEY, DASHSCOPE_API_KEY, MOONSHOT_API_KEY, or MIMO_API_KEY.

See Getting Started and Video Providers for details.

All providers fail / rate-limited

If you only have one API key and that provider is temporarily unavailable, all tools will fail. Add keys for additional providers to enable the fallback chain — GLM and Gemini both have free tiers with no credit card required.

See Video Providers for the fallback chain and API key links.

Large local file fails or uses low-quality frame analysis

GLM-4.6V, Qwen3.6, and MiMo-V2 Omni have a 10–12 MB base64 limit for local files. When a file exceeds this:

The server tries to fall back to Gemini or Kimi (if configured).
If no upload-capable provider is available, it falls back to frame-based analysis (evenly-spaced keyframes) — lower quality.

Best solution: Configure the S3 relay — GLM, Qwen, and MiMo will receive a presigned URL to the full video.

Alternative: Add GEMINI_API_KEY or MOONSHOT_API_KEY to get an upload-capable provider in the fallback chain.

YouTube video fails to download

YouTube downloads occasionally fail due to format changes or network conditions. Try:

Retry — transient failures often resolve on their own.
Use a direct MP4 URL if you can find one (works for all users without download).
Check for updates — the downloader (yt-dlp) is updated regularly:
Terminal window
```
npm install -g video-context-mcp-server@latest
```

Non-YouTube platform URL fails

Vimeo, TikTok, Bilibili, and other non-YouTube platform downloads require the Pro tier. Free users receive an error message for these URLs.

Direct http(s):// URLs pointing to video files (e.g. .mp4, .webm) work for all users.

Transcription fails or returns empty

Check that at least one audio provider key is set (DEEPGRAM_API_KEY, ASSEMBLYAI_API_KEY, GROQ_API_KEY, or GEMINI_API_KEY).
Check that the video has an audio track. Use get_video_info to confirm.
Try a different provider — pass provider: "groq" or provider: "gemini" (both have free tiers).

Transcription ignores the language I specified

Make sure you pass the correct BCP-47 language code (e.g. en, es, fr, ja, zh). Some providers have limited language support — see Audio Providers for details.

S3 relay uploads but the provider still fails

Verify that:

AWS_S3_BUCKET matches an existing bucket in the configured region.
The IAM user / role has s3:PutObject and s3:GetObject permissions on the bucket.
AWS_REGION matches the bucket’s region.

Cache is using too much disk space

Run vmcp cache status to see the breakdown. Then either:

vmcp cache clear:expired — remove old entries
vmcp cache clear:all --yes — wipe the entire cache
Reduce VIDEO_MCP_CACHE_MAX_MB in your config to enforce a lower cap

See Caching & CLI for all cache management commands.