Troubleshooting

./avatar doctor first

Before debugging anything specific, run:

./avatar doctor

It checks the three conda environments, the model files, and GPU access, and tells you which one is wrong. Most problems on this page are things doctor identifies in a second.

The GPU is not visible

nvidia-smi inside WSL2 must list your card. If it does not, the problem is the NVIDIA WSL driver on the Windows side, not Agent Avatar. Install the WSL-enabled driver on Windows — not inside the Linux distribution — and restart WSL.

Out of memory during training

Lower the batch size and train again. Fine-tuning is the most VRAM-hungry stage; if 8GB is not enough at your current settings, a smaller batch will get through. You can resume a run you stopped rather than starting over.

Out of memory during rendering

Lower the MuseTalk batch size. Batch rendering trades VRAM for throughput, so the setting that renders a forty-scene script fastest is not the one that fits in the least memory.

The cloned voice sounds wrong

Almost always the recordings, not the training:

• Background noise — a hum or a fan is learned along with your voice.
• Inconsistent distance from the microphone — varying loudness confuses it.
• Too little material — under 15 minutes is not enough.
• Over-processed audio — heavy compression or noise reduction hurts.

Re-record cleanly before retraining longer. More steps on bad audio just gives you a more confident bad voice.

The lip sync looks off

Your base video is the usual cause. Front-facing, well lit, minimal head movement, and no hands or objects crossing your face. Check a candidate clip before rendering against it rather than after.

For stills, use a high-resolution, front-facing, evenly lit photograph — a professional headshot works well.

The result looks over-smoothed

Face restoration is optional and has a blend dial. Turn it down. Full strength tips into the plastic, uncanny look that makes synthetic video obvious.

The first render is much slower than the rest

Model loading. Call POST /avatars/warm to preload before your first real render, and use batch mode for multiple scenes so the cost is paid once.

Every API request returns 401

If AVATAR_AUTH_SERVER is set, AVATAR_SERVICE_TOKEN must be set too. Setting the first without the second rejects every request.

Disk filling up

Model weights are around 100GB, and rendered clips and intermediate frames accumulate on top of that. Clear old output directories periodically, and take a backup of your trained voice checkpoints before you clean anything — those are the artifacts you cannot regenerate without redoing a recording session.