Runtime troubleshooting
warning
Runtime troubleshooting
Start with evidence
powershell
botconnector doctor --json
botconnector runtime statusCapture: backend, runtime release asset, executable path, model path, context size, port, exit code and stderr. Native errors are kept as-is — they are diagnostic gold; do not retry blindly.
Runtime will not start
| Symptom | Likely cause | Action |
|---|---|---|
| Process exits immediately | Broken/incomplete runtime install | botconnector runtime install to re-fetch |
| "CUDA error" at init | Driver/GPU mismatch | Update driver; try Vulkan; fall back CPU |
| "vulkan device not found" | Driver lacks Vulkan 1.x | Update GPU driver |
| Port already in use | Old instance still running | botconnector ps, stop it, or change --port |
| Antivirus blocks binary | Unknown unsigned binary | Whitelist the runtime path |
Model fails at load
- OOM (out of memory) → smaller quantization or smaller context: Memory problems.
- Checksum mismatch → corrupted download; delete and re-download: Download problems.
- Unsupported architecture → runtime too old for this GGUF version;
botconnector runtime installto update: Runtime.
API never becomes READY
- Confirm state with
botconnector ps(STOPPED/STARTING/READY). - Check the log file in
%USERPROFILE%\botconnector\logs. - Confirm the port is the expected one:
curl http://127.0.0.1:11435/v1/models. - Firewall or AV may block localhost binding — rare, but test with another port.
Logs
Log location: %USERPROFILE%\botconnector\logs. Runtime stderr is preserved per launch — include it when reporting issues.
Related
- GPU problems
- Runtime — lifecycle and backends.