---
title: "Serve LLMs with vLLM Across DGX Sparks — Troubleshooting"
canonical: "https://build.nvidia.com/spark/vllm-cluster/troubleshooting.md"
---

# Common issues

| Symptom | Cause | Fix |
| --- | --- | --- |
| Cluster Assistant cannot finish its checks | One or both Sparks or their ConnectX-7 link needs attention | Return to [Connect Multiple DGX Sparks](https://build.nvidia.com/playbooks/connect-multiple-sparks) and complete its checks before running the recipe. |
| `docker` reports permission denied on either Spark | The device user cannot access Docker | Follow the Docker access check in the [single-device instructions](https://build.nvidia.com/playbooks/vllm/intermediate). |
| Model download reports an authentication error | Hugging Face CLI access is missing or invalid on a Spark | Check `hf auth whoami` on both devices and authenticate as described in the [Hugging Face guide](https://huggingface.co/docs/huggingface_hub/main/en/quick-start#authentication). |
| The API does not respond on the head Spark | The recipe may still be loading or launch may have failed | Check the output in the launch terminal before retrying the `/health` request. |

The cluster recipe and manual launcher have separate setup steps. Use the commands from one path consistently; see **Intermediate** for the recipe or **Advanced** for explicit launch settings.