VidCraft Troubleshooting

Deutsche Version

Back to overview

MCP server does not start or tools are missing

Symptom: Skills report that mcp__vidcraft-mcp__... tools are not available.

Cause: The server only runs with the Python under ~/.vidcraft/venv/ (Windows: %USERPROFILE%\.vidcraft\venv\Scripts\python.exe). If the environment is missing, it does not start.

Fix: Run /vidcraft:setup and restart Claude Code.

Variant: ModuleNotFoundError: No module named 'mcp.server.mcpserver' means the environment has a mcp[cli] that is too old. Running /vidcraft:setup again installs the version pinned in requirements.txt.

New project or change does not show up

Symptom: Right after create_project_structure, create_episode or create_scene, list_projects or get_project_full says the project does not exist. The same applies when you edit files by hand.

Cause: The query tools read the state cache ~/.vidcraft/cache/state.json. It is not rebuilt from the files automatically.

Fix: Run /vidcraft:session-start or call the rebuild_state tool.

"Path outside content root"

Symptom: doc-analyzer, update_field or extract_section refuse a file.

Cause: These tools only work with files below paths.content_root.

Fix: Copy the file into the content root, for example to {content_root}/projects/<project>/research/, or adjust content_root in ~/.vidcraft/config.yaml.

Document analysis fails

• Error "Unsupported format": .md, .pdf and .docx are read. .doc is accepted, see the next item. All other extensions are rejected.
• A genuine .doc file (legacy Word format): It is passed to the python-docx parser, which can only read .docx. This produces a python-docx error that is not caught and shows up as a tool error. Convert the file to .docx first.
• Error "pdfplumber required" or "python-docx required": The packages are missing in the environment. Run /vidcraft:setup.
• Empty result for a PDF: pdfplumber extracts text, not images of text. Scanned PDFs without a text layer yield nothing.

Pre-generation check reports BLOCKED

Cause: The episode status is still Not Started or Script Draft, there are no scenes, or at least one scene has no narration.

Fix: Run /vidcraft:script-reviewer so that the status Script Reviewed is set, and fill empty scenes. The status lives in the frontmatter of the episode README.md. Then rebuild the cache (see above).

HeyGen ignores pauses

Cause: [pause Xs] only works with custom voices (voice clone, ElevenLabs, OpenAI Voice). The public voice library ignores pauses and SSML.

Fix: Use a custom voice or control the pace with punctuation and paragraphs.

Subtitles: Whisper not found

Cause: subtitle-generator calls the whisper command. It is not installed or not on the PATH, or ffmpeg is missing.

Fix: Install pipx install openai-whisper (or pip install openai-whisper) and ffmpeg, see Installation. The exported MP4 should be in the episode's assets folder; otherwise give the skill the file path.

Windows: Python is not found

Symptom: python or python3 exit with code 49 and no output.

Cause: This is the Microsoft Store placeholder, not a real Python installation.

Fix: The setup skill then tries py -3 and known install locations. If Python is really missing, install Python 3.10 or newer with the option to add python.exe to the PATH.

Scene warnings do not appear

The script hooks/validate_scene.py is not registered as a hook and therefore does not run automatically. See Technical.

Settings have no effect

The MCP server only evaluates paths.content_root, paths.video_root, paths.assets_root and defaults.wpm. See Configuration.