N.O.V.A v2 / documentation
Troubleshooting
Symptoms, likely causes and fixes for the errors you are most likely to hit during setup and use.
Find the symptom, check the likely cause, apply the fix. Setup steps are in Installation & Environment.
Install and environment
| Symptom | Likely cause | Fix |
|---|---|---|
AssertionError: Torch not compiled with CUDA enabled | CPU-only torch is installed | Uninstall torch and torchaudio, then reinstall from the cu121 index. See Verify the install |
MemoryError inside pip's cachecontrol or msgpack code | Pip tried to load a huge cached download into RAM | Run python -m pip cache purge, upgrade pip, and install with --no-cache-dir |
Disabling PyTorch because PyTorch >= 2.6 is required, and Coqui says torch is missing | transformers 5.x with torch 2.5.1 | Run python -m pip install "transformers>=4.57,<5" |
pip list shows dozens of packages in a fresh environment | It was created with system site packages | Delete the folder and recreate it with plain python -m venv |
| Packages from other projects broke after an install | The install went into the global Python | Check for the (.venv-tts) prefix and use python -m pip. Confirm pip -V shows a path inside the environment |
| The editor says an import could not be resolved | VS Code is using a different interpreter | Select the .venv-tts interpreter. It is an editor warning only; the code still runs from the terminal |
Voice
| Symptom | Likely cause | Fix |
|---|---|---|
No module named src.output.tts_engine | The filename has a hyphen, or the file is in the wrong folder | It must be src/output/tts_engine.py, with an underscore. Add empty __init__.py files if needed |
Voice sample not found | Wrong NOVA_VOICE_SAMPLE path | Check that the WAV exists. Relative paths start from the project root |
XTTS failed to load, and you hear a Windows voice | Any XTTS load error, with the fallback engine active | Read the error printed just above that line. Set NOVA_VOICE to pick which Windows voice is the fallback |
| Models download to the system drive | TTS_HOME wasn't set when the script ran | Set it in config/.env with an absolute path, then delete the stray copy |
| Speech sounds robotic or off | The pyttsx3 engine is active, or the reference recording is weak | Check NOVA_TTS=xtts. If it is, re-record in a quiet room with a steady mic distance. See Custom Voice |
| No greeting at startup, or it is spoken late | assets/greeting.wav hasn't been created, so N.O.V.A speaks the greeting live and waits for XTTS | Run python scripts/make_greeting.py once. See Fast startup |
| The first spoken reply is delayed after launch | XTTS is still loading in the background | Wait for the engine ready in line in the console. Replies after that are instant |
building the shared engine appears twice in the console | The TTS module is imported under two names (for example tts_engine and src.output.tts_engine), which creates two engines | Import it only as src.output.tts_engine. The module name: in that log line shows which name was used |
Running
| Symptom | Likely cause | Fix |
|---|---|---|
| CUDA out-of-memory error, or very slow replies | XTTS and the language model share the same GPU memory | Set NOVA_TTS_DEVICE=cpu, or use a smaller model. See Settings |
| Voice input crashes at startup | PyAudio is missing | Run python -m pip install PyAudio |