Troubleshooting

Common issues and their solutions when working with the Emotional TTS system.

Docker Issues

Docker build fails with timeout errors

PyTorch packages are large. Increase timeout and retries:

pip install --default-timeout=1000 --retries 20 torch

Container exits immediately

Check logs for errors:

docker logs emotional-tts
docker run -it emotional-tts bash  # Interactive debug

"No NVIDIA GPU found" in Docker

# Install NVIDIA Container Toolkit
sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Verify
docker run --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

Model Issues

Model fails to load

Verify checkpoint files are present:

ls -la Docker/checkpoints/
# Should contain: config.yaml, gpt.pth, dvae.pth, bigvgan_generator.pth, bpe.model

Out of GPU memory

The model requires ~4-6 GB VRAM. If running out:

• Reduce MAX_WORKERS to 1
• Process shorter texts
• Use FP16 mode (enabled by default on GPU)
• Close other GPU-using applications

"Model not loaded" (503 error)

The model takes 30-60 seconds to load on startup. Wait and retry:

# Wait for model to load
watch -n 5 'curl -s http://localhost:8000/health | python3 -m json.tool'

API Issues

CORS errors in browser

The API allows all origins by default. If using a reverse proxy, ensure CORS headers pass through.

File format not supported

Accepted formats: WAV, MP3, FLAC, OGG, M4A. Convert with ffmpeg:

ffmpeg -i input.mp4 -ar 22050 -ac 1 output.wav

Audio too short error

Speaker reference must be at least 5 seconds. The system auto-pads shorter files, but quality is better with naturally longer recordings.

Output files disappearing

Files auto-delete after FILE_TTL_SECONDS (default: 2 hours). Download results promptly or increase TTL.

Audio Quality Issues

Generated audio sounds robotic

• Use a cleaner speaker reference (less background noise)
• Try a longer reference audio (10+ seconds)
• Ensure the reference audio is speech, not music

Emotion not clearly expressed

• For vector mode: increase emo_alpha (try 1.5 or 2.0)
• For reference mode: use a more emotionally expressive reference
• Match text content to the emotion for more natural results

Linux Deployment Issues

Permission denied errors

# Fix Docker socket permissions
sudo usermod -aG docker $USER
newgrp docker

Port already in use

# Find what's using the port
sudo lsof -i :8000
# Or use a different port
docker run -p 9000:8000 emotional-tts-api