| Symptom | Cause | Fix |
|---|---|---|
| Container fails to start with GPU error | NVIDIA Container Toolkit not configured | Install nvidia-container-toolkit and restart Docker |
| "Invalid credentials" during docker login | Incorrect NGC API key format | Verify the API key from the NGC portal; ensure no extra whitespace |
| Model download hangs or fails | Network connectivity or insufficient disk space | Check internet connection and available disk space in the cache directory |
| API returns 404 or connection refused | Container not fully started or wrong port | Wait for container startup completion; verify port 8000 is accessible |
| runtime not found | NVIDIA Container Toolkit not properly configured | Run sudo nvidia-ctk runtime configure --runtime=docker and restart Docker |
| Memory pressure within capacity | Unified memory buffer cache not released | See UMA note below |
NOTE
Some hardware platforms use Unified Memory Architecture (UMA), which enables dynamic memory sharing between the GPU and CPU. If you hit memory pressure even when within rated capacity, manually flush the buffer cache with:
sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'
For latest known issues, see the documentation linked under Resources for your hardware platform.