Troubleshooting

Audio version — Estimated duration: 8 min 46 sec

CUDA not available

Error: CUDA is not available. GPU is required.

Root cause: PyTorch can’t find a CUDA-capable GPU or the CUDA driver isn’t loaded.

Diagnostics:

nvidia-smi                          # Check GPU and driver
python -c "import torch; print(torch.cuda.is_available())"  # Check PyTorch CUDA

Fixes (in order of likelihood):

1. Install the matching PyTorch for your CUDA version:

   pip install torch --index-url https://download.pytorch.org/whl/cu124

   Check your CUDA version with nvidia-smi (top-right) and match the index URL.

2. Update NVIDIA drivers — on Linux:

   sudo apt install nvidia-driver-545   # Ubuntu/Debian

   On Windows, download from nvidia.com/drivers.

3. If using WSL2 on Windows, install CUDA support inside WSL:

   sudo apt install nvidia-cuda-toolkit

Model load fails

RuntimeError: Could not load model with any supported attention backend.

Root cause: The model directory is missing, incomplete, or incompatible.

Check:

ls ./Qwen3-TTS-12Hz-0.6B-CustomVoice/

Should contain: config.json, model-00001-of-00002.safetensors (or similar), tokenizer.json, etc.

Fixes:

• Download the full model using Git LFS or huggingface-cli (see Installation)
• Verify the path matches what you pass to --model-path / --model_path
• Try --dtype float32 (CustomVoice) — some systems have issues with bfloat16 loading
• If using a symlink, ensure it points to a valid directory with read permissions

Out of memory (CUDA OOM)

torch.OutOfMemoryError

Root cause: The model + batch + chunk don’t fit in GPU VRAM.

Priority fixes (most effective first):

1. Lower --batch-size / --batch_size to 1
2. Lower --max-chars / --chunk_size to 100
3. Switch dtype: --dtype bfloat16 (Ampere) or --dtype float16
4. Close other GPU-using applications (browsers with GPU acceleration, other ML scripts)
5. Clear cached memory before running:

   import torch; torch.cuda.empty_cache()

6. Restart your Python process (VRAM may be fragmented)

VRAM budget (approximate, for a 0.6B model):

Usage	VRAM
Model weights (float16)	~1.2 GB
Activations per chunk	~0.3–0.5 GB
Overhead	~0.5 GB
Total minimum	~2.5 GB

With batch_size 1 and max_chars 150, a 6 GB card has comfortable headroom. Batch_size 4 and max_chars 300 may OOM.

Device-side assert

"device-side assert triggered" — CUDA context is dead, all subsequent CUDA calls fail

Root cause: Usually special characters in the text that cause the model’s tokenizer or embedding layer to produce out-of-range indices.

Fixes:

• The CustomVoice script strips non-ASCII automatically. If using the Base script, clean your input first.
• Convert the Markdown file to pure ASCII:

  python -c "print(open('input.md').read().encode('ascii', 'ignore').decode('ascii'))" > clean.md

• Remove emoji, mathematical symbols, curly quotes, and other non-printing characters from your input file.
• After this error, the CUDA context is dead. You must restart the Python process. Any subsequent GPU calls from the same process will fail until restart.

Voice cloning quality is poor

Symptoms: Cloned voice sounds robotic, wrong accent, or doesn’t match the reference.

Likely causes:

Cause	What to check
Transcript mismatch	Is --ref_text word-perfect? Listen and retype.
Noisy reference	Does the reference WAV have background noise, music, or reverb?
Wrong language	Does --lang match both reference and input text?
Reference too short	< 3 seconds doesn’t give the model enough voice information
Reference too long	> 30 seconds may contain multiple prosodic variations that confuse the embedding
Multiple speakers	Is there only one person in the reference?

The transcript is the #1 cause of poor clones. Even a single wrong word or contraction changes the embedding. Transcribe manually, or use a speech-to-text tool and then correct every error.

Batch fails, falls back to sequential

The Base script prints:

Batch failed: .... Falling back to sequential.

This is not an error — it’s the script adapting to VRAM pressure. Each chunk will be processed one at a time, which is slower but stable. If this happens frequently, lower --batch_size or --chunk_size.

Silent or empty output

Saved to output.wav

But the file has no audible content or is very short.

Check:

python -c "import soundfile as sf; d, sr = sf.read('output.wav'); print(f'{len(d)/sr:.1f}s')"

Fixes:

• Your input Markdown file may be empty after cleaning. Check with:

  python -c "import re; print(re.sub(r'\[([^\]]+)\]\([^\)]+\)|[*_~`#>]|<[^>]*>', '', open('sample.md').read()).strip())"

• Very short input files (< 50 chars after cleaning) may produce zero chunks. Try --chunk_size 300 or --max-chars 300 to keep everything in one chunk.
• Check that the output directory is writable.

local_files_only=True error

OSError: Can't load the model because 'local_files_only' is True but no local files were found.

Root cause: --model-path / --model_path points to a non-existent or empty directory.

Fix: Verify the model path and download the model if missing.

ls -la ./Qwen3-TTS-12Hz-0.6B-CustomVoice/

If empty or missing, download from Hugging Face (see Installation).

Speaker not found

Speaker 'XX' not found. Available: [...]. Defaulting to serena.

Fix: Use one of the listed speaker names. Names are case-insensitive so "aiden" works for "Aiden". See the full list.

Slow generation

Symptoms: Much slower than expected for the GPU.

Diagnostics:

# Check GPU utilisation during generation (separate terminal)
watch -n 0.5 nvidia-smi

If GPU utilisation is below 80%, the bottleneck is likely:

1. Token budget too high — are chunks hitting 1024 tokens? CustomVoice’s adaptive budget should help, but if chunks are long they’ll saturate.
2. Batch size too low — increase --batch-size if VRAM allows (check with nvidia-smi).
3. Using float32 — switch to bfloat16 or float16.
4. CPU bottleneck — Markdown cleaning and chunk splitting are negligible, but if the model is on CPU (check nvidia-smi), that’s the problem.

Expected performance (RTX 3050 6 GB, CustomVoice, bfloat16, batch-size 1, max-chars 150):

Text length	Chunks	Time
300 chars	2	~8s
1000 chars	7	~42s
5000 chars	33	~5 min

Path not found

Error: Input file 'X' not found.

Fix: Use an absolute path or a relative path from the project root:

python md_to_audio_custom.py ./sample.md --speaker "Aiden"

---

Still stuck? Check GPU Optimization for tuning tips.