Troubleshooting

Start with the logs. For models, open Worker log on the Generate tab. For model installs, see Install log on the Models tab. For training, open Training log. The app log is in logs/.

Installation

Setup script fails

• Install uv and run the script again. uv brings its own Python, so a missing or old system Python doesn't matter.
• Linux / macOS: if you get "Permission denied", run chmod +x scripts/*.sh.
• Windows: run scripts\setup.bat from Command Prompt or by double-clicking it.

A model won't install

• Open the Install log on the Models tab for the error.
• Click Reinstall to recreate the environment from scratch. From the CLI: openvoicelab install <id> --reinstall.
• If the log shows a package failing to build, install a C compiler and retry: build-essential on Debian/Ubuntu, or the Xcode command-line tools (xcode-select --install) on macOS.

Port 7860 already in use

./scripts/run.sh --port 8080

Loading models

A model fails to load

Open Worker log for the full error. Common causes:

• Out of memory: unload other models and close other GPU apps, then pick a smaller checkpoint or set Device to cpu.
• Gated model (401/403 errors): accept the model's terms on Hugging Face, then run hf auth login. Pocket TTS voice cloning needs this.
• Broken environment: reinstall the model from the Models tab.

Download is slow or interrupted

Weights download from Hugging Face on first load and are cached in ~/.cache/huggingface. If a download is interrupted, load again and it resumes.

CUDA not used

The app footer shows the detected devices. If your NVIDIA GPU isn't listed:

1. Update your NVIDIA driver.
2. Run ./scripts/update.sh. It reinstalls PyTorch with --torch-backend=auto, which picks the CUDA build that matches your driver.
3. Reinstall the model from the Models tab.

Apple Silicon

Models run on MPS automatically. A few (Pocket TTS, Kitten TTS, MOSS-TTS Nano) run on CPU instead, because it's faster or more reliable there. If a model misbehaves on MPS, set Device to cpu.

Generation

Output is garbled, cut off or in the wrong voice

• Generate again with a different seed, since most models are random.
• Use a cleaner reference clip, 5-20 seconds long and with only one speaker.
• If the model uses a transcript, make sure it matches the clip exactly.
• Set Language explicitly instead of Auto.
• Reset any Advanced settings you changed back to their defaults.

Background music in VibeVoice output

This is a known VibeVoice behavior that comes from its training data. Try a different seed or a cleaner reference clip.

"Chatterbox Turbo/Nano need a reference clip longer than 5 seconds"

Use a longer clip, or switch to the original Chatterbox or Multilingual checkpoint.

Generation is slow

• Large models are slow on CPU, so use a GPU when you can.
• Pick a smaller checkpoint.
• Lower the number of diffusion steps in Advanced settings, for models that have that setting.
• For speed on CPU, use Kokoro, Kitten TTS or Pocket TTS.

Data and training

"No speech found in the input files"

The audio is too quiet or too noisy, or isn't speech. Normalise the volume or use cleaner recordings.

Training runs out of memory

Lower the batch size (and raise the gradient accumulation steps to compensate), turn on gradient checkpointing, or lower the LoRA rank. Fine-tuning VibeVoice 1.5B needs about 16 GB of VRAM.

Training fails to start

Install VibeVoice on the Models tab first, since training runs in its environment. Check training_runs/run_<timestamp>/train.log for the error.

TensorBoard doesn't show

Wait for the first metrics to be logged, then click Show TensorBoard again. TensorBoard only works on the machine running OpenVoiceLab.

Getting help

Ask on Discord or open a GitHub issue. Include:

• your OS and GPU, plus the device line from the app footer;
• the model family and checkpoint;
• the error from the Worker, Install or Training log;
• the steps to reproduce the problem.