Is this page helpful?

Troubleshooting#

This page covers the most common first-run failures and their fixes. If you hit something not listed here, file an issue with the exact error text.

Setup#

setup_sample.bat fails on a fresh Windows host#

Symptom

PackageManagement\Install-Module : NuGet provider is required to continue

or extraction errors right after that, or Expand-7Zip is not recognized.

Cause

A clean Windows 11 image does not have the NuGet PowerShell package provider installed. Install-Module 7Zip4Powershell fails non-interactively because it cannot prompt for the provider bootstrap.

Fix

Update to the current setup_sample.bat, which now bootstraps the NuGet provider explicitly. If you are stuck on an older version, run this once in an elevated PowerShell:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force -Scope CurrentUser
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
Install-Module -Name 7Zip4Powershell -Force -Scope CurrentUser -AllowClobber

Then re-run setup_sample.bat.

Voice cloning#

UnicodeEncodeError: 'charmap' codec can't encode character#

Symptom

UnicodeEncodeError: 'charmap' codec can't encode character '\u2713' ...

appears at the end of get_voice_embeddings.py after the model has run. The JSON may not be written.

Cause

The script’s stdout is being written through the default Windows console code page (cp1252), which cannot encode the U+2713 ✓ character that older versions printed.

Fix

The current script prints [OK] instead. If you are stuck on an older version, set PYTHONUTF8=1 before invoking:

$env:PYTHONUTF8 = "1"
python get_voice_embeddings.py ...

ModuleNotFoundError: No module named 'chatterbox'#

Cause

The venv at voice_cloning\venv\ is not activated in the current shell, so python is resolving to the system / bootstrap interpreter, which does not have torch or chatterbox-tts installed.

setup_venv.ps1 activates the venv automatically only for the shell that ran it. In a fresh shell you have to activate it manually.

Fix

cd voice_cloning
.\venv\Scripts\Activate.ps1
python get_voice_embeddings.py ...

After activation your prompt will be prefixed with (venv). To double-check:

where.exe python   # should show ...\voice_cloning\venv\Scripts\python.exe first
python -c "import torch, chatterbox; print('ok')"

get_voice_embeddings.py runs slowly (~10 s per WAV)#

Cause

Torch installed without CUDA support — almost always because PyPI’s default index returned the CPU wheel. Confirm with:

.\venv\Scripts\python.exe -c "import torch; print(torch.cuda.is_available(), torch.__version__)"

If the first value is False or the version string lacks a +cuXXX suffix, torch is CPU-only.

Fix

The current requirements.txt pins torch==2.6.0+cu124 via an explicit --extra-index-url. Recreate the venv:

Remove-Item -Recurse -Force .\venv
.\setup_venv.ps1

If you sit behind a corporate proxy that blocks download.pytorch.org, configure your proxy or download the wheel manually and pip install it from disk before re-running setup.

You can also re-extract a custom voice with the venv active:

.\venv\Scripts\Activate.ps1
python get_voice_embeddings.py --wav reference.wav --dump-json out.json --hf-token $env:HF_TOKEN

Voice cloning runs on CPU even though the GPU is CUDA-capable (RTX 50-series / Blackwell)#

Symptom

get_voice_embeddings.py starts with a multi-line [device] WARNING block and Using device: cpu even though torch.cuda.is_available() is True. The warning lists the GPU, the installed torch version, and the arch list — typically something like:

gpu     : NVIDIA GeForce RTX 5090 (sm_120)
torch   : 2.6.0+cu124
arches  : ['sm_50', 'sm_60', 'sm_61', 'sm_70', 'sm_75', 'sm_80', 'sm_86', 'sm_90']

Extraction completes correctly but takes ~10–14 s per WAV (vs ~1–2 s on a supported GPU).

Cause

The packaged torch==2.6.0+cu124 (selected to match chatterbox-tts 0.1.7’s pin of torch==2.6.0) ships pre-built CUDA kernels for compute capabilities up to sm_90 (Hopper). Blackwell (RTX 50-series, B100, sm_120) is compute capability 12.0, which shares no binary compatibility with any kernel in the wheel. The first real CUDA op would crash with CUDA error: no kernel image is available for execution on the device, so the script does a probe at startup and gracefully falls back to CPU instead of crashing mid-inference.

The first PyTorch release with sm_120 kernels is torch>=2.7 from the cu128 wheel index. We do not pin that combination by default because it breaks chatterbox-tts==0.1.7’s torch==2.6.0 dependency contract and forces a --no-deps install.

Fix (CPU is fine — most users should do nothing)

CPU extraction is correct and produces bit-identical speaker JSONs to the GPU path. If extraction speed is acceptable, you can ignore the warning. The generated speaker JSON works at full speed with the plugin / CLI at TTS time — only the one-off extraction step uses CPU; the runtime TTS sample continues to use the GPU through the NVIGI CUDA plugin.

Fix (opt-in GPU acceleration on Blackwell)

If you want GPU extraction on a Blackwell card and accept the broken pin, replace the default torch stack in the voice-cloning venv:

cd voice_cloning
.\venv\Scripts\Activate.ps1
pip install --pre torch torchaudio `
    --index-url https://download.pytorch.org/whl/nightly/cu128
# chatterbox-tts==0.1.7 hard-pins torch==2.6.0; bypass the pin:
pip install --no-deps chatterbox-tts==0.1.7

Re-run get_voice_embeddings.py. The runtime probe will now succeed, the script will report Using device: cuda, and no [device] WARNING block will appear. Extraction drops back to ~1–2 s per WAV.

This is unsupported by the packaged dependency contract; if you update chatterbox-tts or any of its transitive deps after this, you may need to redo the override.

Hugging Face authentication errors#

Symptom

A long traceback ending in RepositoryNotFoundError, GatedRepoError, or HfHubHTTPError. Or a successful run despite no HF_TOKEN / --hf-token, that produces unexpected outputs.

Cause

  • Missing or invalid token, or

  • A stale token cached at ~/.cache/huggingface/token is being used silently.

Fix

The current get_voice_embeddings.py prints the token source on startup:

[hf-token] source: HF_TOKEN environment variable
[hf-token] source: --hf-token argument
[hf-token] source: cached token at C:\Users\<you>\.cache\huggingface\token (WARNING: pass --hf-token or set HF_TOKEN to be explicit)
[hf-token] source: none (public-only access)

For automated / CI runs, always pass an explicit token:

python get_voice_embeddings.py --hf-token $env:HF_TOKEN ...

To clear a stale cached token:

Remove-Item "$env:USERPROFILE\.cache\huggingface\token" -ErrorAction SilentlyContinue
huggingface-cli login   # then enter the new token

Runtime#

Speaker / model mismatch (silent or garbled audio)#

Symptom

createInstance fails with:

Speaker / model mismatch: speaker JSON 'XXX.json' was produced for the
turbo model but the runtime is multilingual. ...

Cause

The speaker embedding JSON contains a model_type field (turbo / multilingual) that does not match the runtime model selection (--multilingual flag or eMultilingual enum value at instance creation). Turbo and multilingual embeddings have identical shapes but are not interchangeable — using a mismatched JSON produces silent or garbled audio.

Fix

  • Use the matching JSON: turbo speakers (e.g. aaron_turbo.json, lucy_turbo.json) only with turbo, multilingual speakers (e.g. the per-language JSONs and *_multilingual.json) only with multilingual.

  • Or re-extract the embedding with the correct --model-type argument:

    python get_voice_embeddings.py `
  --wav ref.wav --model-type multilingual `
  --dump-json my_voice.json --hf-token $env:HF_TOKEN

A speaker JSON that was created before this validation existed will not have a model_type field. The plugin accepts it with a warning rather than rejecting it. Re-run get_voice_embeddings.py to add the field.

createInstance failed: 0x...#

Symptom

ERROR: createInstance failed (0x4000000 = kResultInvalidState)
  models dir : "..."
  model GUID : "{...}"
  ...

Cause

Most commonly the model files for the requested GUID are missing or the backend plugin DLL was not copied into bin\x64\<config>\.

Fix

  1. Verify the GUID directory exists under data\nvigi.models\nvigi.plugin.tts.chatterbox\. If absent, re-run the model download script in that directory.

  2. Verify nvigi.plugin.tts.chatterbox.<backend>.dll exists in bin\x64\<config>\ (where <backend> is cuda, vk, or d3d12).

  3. Re-run setup_sample.bat if either is missing.

--text "" falls through to “missing required” error#

Cause

Older builds did not distinguish “user passed an empty string” from “user forgot the flag”. The current build emits a specific message (”--text was provided but its value is an empty string”) for the empty case.

Fix

Pass a non-empty string. If your invocation is built up from a script variable, log the value before invoking to verify it is non-empty.

--backend vk rejected#

Cause

Older nvigi.tts.chatterbox.exe only accepted --backend vulkan. The 3D sample uses -vk.

Fix

The current build accepts both --backend vulkan and --backend vk for consistency with the 3D sample. Update to the current build, or pass --backend vulkan.

nvigi.3d.exe crashes immediately under SSH#

Symptom

STATUS_ACCESS_VIOLATION (-1073741819) within seconds, no log output, no ..\logs\ directory created.

Cause

OpenSSH / Windows-service shells run in session 0, which has no interactive desktop. D3D12 / DXGI swapchain creation requires a desktop session.

Fix

The current build refuses to start in session 0 with a clear message. Use one of:

  • RDP into the host and launch from a normal shell.

  • Run from the local console.

  • psexec -i <session-id> to attach to an existing desktop session.

If you are seeing the access violation rather than the new message, you are running an older build — update to the current pack.