Troubleshoot AngeVoice

Collect a minimal baseline before changing configuration. Change one variable at a time.

DockerModelsLogs

Run these checks first

curl -s http://127.0.0.1:8100/health | python3 -m json.tool
curl -s http://127.0.0.1:8100/v1/models | python3 -m json.tool
docker ps --format "table {{{{.Names}}}}\t{{{{.Status}}}}\t{{{{.Ports}}}}"
docker logs --tail 200 <container-name>
df -h

Diagnose by symptom

Symptom	Likely cause	First action
Model download never finishes	Missing model, incomplete cache or Git LFS pointer	Inspect file headers and sizes; remove pointer files and download again
Health stays at loading	First download, CUDA initialization or missing persistent mount	Follow logs and confirm the model directory is growing
GPU OOM	Several loaded models, multiple workers or a long reference	Use one worker, load one model and shorten reference audio
MOSS is unavailable	Missing runtime, wrong path or incompatible image	Read the unavailable reason in `/v1/models`
Cloning is not supported	The request reached Kokoro or no cloning model was selected	Set `model=moss` or `zipvoice`
WebSocket connects but plays no audio	First message, token, proxy Upgrade or PCM playback	Test a direct connection first
401	Missing or incorrect API key	Copy the key from the admin page and send a Bearer token
MP3 fails	FFmpeg or MP3 output is disabled	Validate WAV first, then run `ffmpeg -version`

Recognize a Git LFS pointer

head -5 models/models--hexgrad--Kokoro-82M-v1.1-zh/kokoro-v1_1-zh.pth

If the file begins with version https://git-lfs.github.com/spec/v1, it is not a real model weight:

git lfs install
git lfs pull

Do not disable weights-only loading to hide this error. Untrusted PyTorch weights can execute code.

Check GPU fallback

nvidia-smi
curl http://127.0.0.1:8101/v1/models/current
docker logs --tail 200 angevoice-gpu | grep -Ei "cuda|cudnn|oom|fallback"

Cloning problems

MOSS reference audio does not belong in the Kokoro voices/*.pt directory.
HTTP uses multipart upload. WebSocket uses base64 or a data URL in prompt_audio.data.
Long reference audio increases VRAM use, latency and distortion risk.
For boundary noise, inspect clipping and compare with real-time frame decoding disabled.

Reverse proxy

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;

If direct access works but the proxy fails, inspect Upgrade headers, request size and timeouts.

Generated audio is not persisted

ANGEVOICE_SAVE_OUTPUTS=true
ANGEVOICE_OUTPUT_DIR=/app/outputs
ANGEVOICE_OUTPUT_MAX_FILES=1000

Also mount /app/outputs to persistent storage. HTTP and batch endpoints can save results; WebSocket streaming does not write files by default.

The voice list is empty

ls -lh models/models--hexgrad--Kokoro-82M-v1.1-zh/voices/
docker exec -it <container-name> ls -lh /app/models/models--hexgrad--Kokoro-82M-v1.1-zh/voices/

If the directory is empty or contains only Git LFS pointers, download the real voice files and verify the model-volume mount.

The API returns 429

Back off according to Retry-After. Reduce client concurrency before changing server limits. Disable or raise QPS protection only when an upstream proxy provides equivalent controls.

grep -E 'KOKORO_ADMIN_ENABLED|ANGEVOICE_ADMIN_USERNAME|ANGEVOICE_ADMIN_PASSWORD' docker/angevoice.env

Confirm that the admin console is enabled, the credentials directory is writable and the same directory is mounted after restart. After a password change, only the new credentials work; the application does not retain a recoverable plaintext password.

Before reporting an issue

Include the version, deployment profile, hardware, redacted health output and relevant logs. Remove API keys, Authorization headers, administrator passwords and provider secrets.