Troubleshooting
The failures worth naming before you meet them.
| The runtime is not ready | A large model takes time to load. Ask the health endpoint rather than restarting: it distinguishes a slow start from a dead process. |
|---|---|
| Out of memory | The model is larger than the machine can hold. Move to a smaller validated profile. |
| The port is busy | Something else holds 5000. Map a different host port; the container keeps its own. |
| Authorisation failed | The token is per-machine. Re-read it from the machine running the runtime rather than reusing another. |
| Docker cannot see the GPU | The NVIDIA container runtime has to be installed and passed through. Without it the container runs on CPU. |
| macOS containers are slow | A container on macOS cannot reach Metal, so it is CPU-bound. The desktop application is the right route on a Mac. |
| A document search finds nothing | Retrieval is lexical. Try the words the document itself would use. Check the collection indexed the folder you meant. |
| Streaming looks stuck | Delivery is buffered rather than token-native, so text can arrive in groups. |
When sending logs, read them first. Remove tokens, file paths and anything from a client document before it leaves your machine.