Troubleshooting

Check an installation and fix common errors.

Check the installation

pionus doctor
# offline
pionus doctor --thorough
# also hash the model file (minutes for a big model)

One line per check: ok, warn or fail, with the fix. It exits 1 if anything fails.

Check	Looks at
`path`	the directory of the running binary is on `PATH`
`git`	git runs and is 2.20 or newer
`config`	config files read fine
`model`	the model files exist and match
`llama.cpp`	llama-server is installed, and is the build this release pins
`device`	the device exists, and a benchmark was run
`server`	the models kept loaded
`hook`	the hook is installed and runs this binary

Example:

ok    path       /home/me/.local/bin is on PATH
ok    git        git 2.43
ok    config     no files: the defaults apply
ok    model      qwen2.5-coder-1.5b-instruct-q4_k_m.gguf: size and record match (--thorough hashes the file)
ok    llama.cpp  /home/me/.local/share/pionus/llama.cpp/llama-b11381/llama-server
ok    device     cpu (auto: no benchmark, the default order)
warn  device     no benchmark yet - run `pionus bench`
ok    server     none running: the next commit starts one
warn  hook       not installed in this repository - `pionus hook install`

Messages and what to do

Message	What to do
`pionus is not set up yet`	Run `pionus setup`.
`no device could run the model`	Run `pionus setup`. The message lists what each device lacks.
`no model in …`, `no GGUF model at …`, `no llama-server at …`	Run `pionus setup`, or `pionus model use <id>`.
`… has no OpenVINO version, which npu needs`	This model runs on `vulkan` and `cpu` only. For the NPU: `pionus model use qwen2.5-coder-1.5b`.
`OpenVINO GenAI not found`	Only `npu`, `intel-gpu` and `openvino-cpu` need it. Use `vulkan` or `cpu`.
`model.device = gpu … is the old name of intel-gpu`	`pionus device use intel-gpu` (or `auto`).
`cannot load the model on the NPU`	Run `~/.local/share/pionus/scripts/check-npu.sh`. After joining the `render` group, log out and back in.
NVIDIA GPU `has no driver bound`	Install a driver (`sudo ubuntu-drivers install`) or use nouveau, then `pionus setup`.
The hook does nothing	It acts on `git commit` without `-m`. Reinstall it with `pionus hook install`.
Anything else, or you do not know what is wrong	Run `pionus doctor`.

Report a bad message

pionus --trace bad.json
# or: PIONUS_TRACE=bad.json git commit
pionus replay bad.json
# checks that it reproduces

A trace holds your staged diff and recent commit subjects. Review it before sharing. pionus -v shows what was decided; pionus prompt shows the prompt.

All commands: the usage guide.