Skip to content

Troubleshooting

Each entry names the symptom, the likely cause and the fix. If you see a message code such as llm-all-failed or qc.loudness, look it up in Messages and error codes.

When a run stops, the project moves to Needs you with a plain message and what to do. Try again re-runs only the step that failed; finished steps are kept, and a project made on autopilot goes on on autopilot.

Message What to do
The voice kept leaving out a sentence in scene N: “…” Reword or split that sentence in the script, then Try again. Tips: Voices
The voice could not read scene N, even in two halves: “…” Same: shorter sentences, simpler wording, a rare word reworded
The free voice isn’t downloaded on this computer yet Download the free voice (about 330 MB; progress in Settings › Advanced › Downloads), then Try again
There’s no OpenAI key in Reelfold, so this step couldn’t run Use the free voice (Apple silicon), or add the key in Settings › AI
The visuals need an AI model — Claude Code didn’t answer Try again (it gets more time), or choose another model in Settings › AI. See AI providers
Scene N of M couldn’t be redrawn: … Your video is unchanged Nothing is lost. Try again redraws only the missing scenes, or Redraw scene N later
The script wasn’t written in scenes yet — it was still your notes Try again: the scenes are drafted from your notes
Reelfold couldn’t render this — this is a bug in the app, not a problem with your files Press Report this problem. It shows the report (no file names, transcripts or keys) and opens it on GitHub for you to post
“…” couldn’t be read The file is damaged or not a video Reelfold can open. Check it still plays, then Try again
“…” is on the drive “…”, which isn’t connected Connect the drive, then Try again
Node.js didn’t run / ffmpeg didn’t run The message names the fix, for example brew reinstall node, or reinstall Reelfold

A redo of a finished video that stops (new visuals, new vertical versions) never breaks the clip: it stays Ready to post with its old video, and the notice says what stopped.

The engine looks for ffmpeg and ffprobe on your PATH, then falls back to the static-ffmpeg package.

  • Install it: brew install ffmpeg.
  • Or point at specific binaries: VSTUDIO_FFMPEG=/path/to/ffmpeg and VSTUDIO_FFPROBE=/path/to/ffprobe.

VSTUDIO_H264_ENCODER (or persona export.h264_encoder) chooses the encoder: libx264 (default), h264_videotoolbox on macOS, h264_mf on Windows. The engine test-encodes the chosen one once. If it doesn’t work on this machine, everything falls back to libx264 on its own, and a failed hardware encode is re-run with libx264. Nothing to fix unless you want the hardware encoder; then check your ffmpeg build supports it.

Whisper model download is slow, or you’re offline

Section titled “Whisper model download is slow, or you’re offline”

The first transcription downloads the model into the Hugging Face cache (~/.cache/huggingface/hub, or $HF_HOME/hub): whisper-large-v3-turbo for mlx-whisper on Apple Silicon, large-v3-turbo for faster-whisper elsewhere.

  • Let the first download finish once on a good connection; later runs reuse it.
  • To use a model you already have: VSTUDIO_WHISPER_MLX=/path/to/whisper-large-v3-turbo-mlx or VSTUDIO_WHISPER_FW=/path/to/faster-whisper-large-v3-turbo (a size name such as small also works).
  • Add HF_HUB_OFFLINE=1 so it never touches the network.

A font role (cjk, cjk-bold, serif, mono …) is missing from ~/.cache/video-studio/fonts. Anything drawn with it uses a fallback face, which is why the warning is loud.

  • Run ./install.sh again; it downloads the open-licensed fonts.
  • Or point the role at your own file in persona.local.yaml under fonts:. One face of a collection works as path/to/Fonts.ttc#N.

“model ‘…’ not found” (MediaPipe)

Section titled ““model ‘…’ not found” (MediaPipe)”

Face tracking, retouch, cover frame picking and matting use the MediaPipe face landmarker and segmenters. ./install.sh downloads them into ~/.cache/video-studio/models. Run it again if one is missing. Without a model, cover layouts fall back to a centred crop.

The installed app carries its own engine. If a source build says the engine isn’t running or can’t start, the status line in Settings names it.

  1. Open Settings › Advanced › Engine. It shows the video engine, the Python and the engine data folder in use.
  2. Point the video engine at the folder that contains lib/vstudio, and Python at an interpreter that has requirements.txt installed, then Restart the engine.
  3. The same can come from the environment: VSTUDIO_ENGINE_PATH for the engine and DESK_PYTHON for Python. The app looks at Settings first, then those variables, then the repo it lives in.

Everything is cached under $VSTUDIO_CACHE, by default ~/.cache/video-studio. Older builds wrote some of it to ~/.cache/vstudio. That folder is still read but no longer written; delete it once you no longer need it.

“Every AI provider failed” (llm-all-failed)

Section titled ““Every AI provider failed” (llm-all-failed)”

The routed provider and all its fallbacks failed. The message lists which ones were tried.

  • Check what this Mac has: python3 -m vstudio.llm auth status, run from the repo’s lib folder, or Settings › AI in the app.
  • Fix the first failing one (login, key, local server), or add a fallback: in the app, per task; in the persona, fallback: [codex, ollama] on the route.

A notice like llm-fallback (“Claude Code failed; Codex answered instead”) is not an error. The work was done by the next provider in the chain.

The app checks Claude Code with a one-line round trip, because its own status can still say “logged in” after the token expired.

  • In the app: Settings › AI › Sign in again. Your browser opens; if it shows a code, paste it into the app.
  • In a terminal: run claude, then /login (or claude auth login).

The engine never sees your password or token. Nothing is lost when a run stops on an expired login: sign in, run it again, and finished stages are not redone.

“No model” or “didn’t answer” in the chat

Section titled ““No model” or “didn’t answer” in the chat”

No model means nothing is connected: sign in, add a key or start a local model in Settings › AI. “The model didn’t answer this time” means one is connected but did not reply in time; Try again gives it more time. If you set a model for Codex, make sure your account can use it; an unsupported model fails every call. Time limits, effort and fallbacks: AI providers.

  • Run estimate before a large batch. After one pilot on an otherwise idle Mac, estimates use your machine’s measured speed (bench prints the table).
  • Transcription runs one at a time (whisper owns the GPU); rendering runs a few in parallel. Lower --concurrency cpu-render=2 if your Mac is also busy with other work; raise it only if it isn’t.
  • VSTUDIO_H264_ENCODER=h264_videotoolbox uses the Mac’s hardware encoder for every encode.
  • Retouching long videos: the fast preset is about three times faster than quality.
Terminal window
python3 -m vstudio.batch du --batch <batch> # what uses the space
python3 -m vstudio.batch clean --batch <batch> # delete regenerable intermediates

clean keeps JSON, covers, sheets and previews. For delivered client batches, cleanup-sources lists source files past their cleanup date (a dry run) and only deletes with the code it printed. Your own recordings outside the batch folder are never deleted.

Names or terms are spelled wrong in captions

Section titled “Names or terms are spelled wrong in captions”

Speech recognition writes names by sound.

  • Proofreading with entity checks runs before captions are burned: place names are matched to their standard spelling, and your glossary terms are applied the same way everywhere. Run it, don’t skip it.
  • Add your own fixes to persona.local.yaml: subtitles: {term_fixes: [["[Tt]runking", "chunking"]]} (a regex and its replacement). Client batches use the client’s glossary.
  • Pass key terms to transcription up front (asr: {prompt: "LangChain, RAG"}).
  • Fix a single caption in review. A change that adds or drops a spoken word is refused unless a re-hearing of that audio confirms it.
  1. python -m vstudio.cleanup verify OUTPUT re-transcribes the cut. A lost content word fails with its source and output time.
  2. Keep the edit that covers it: reply 保留 7 (or --keep 7) and apply again.
  3. If it keeps happening, use a gentler profile (gentle keeps more pause and breath), or add words to cleanup.never_cut in the persona.

In the app, filler cuts that might be real words wait for your yes in the Inbox; answer “keep” for the ones you want.