# Troubleshooting

## `gpu-doctor` reports no GPU

Confirm the driver and Vulkan/CUDA runtime are installed, then run the doctor
under the same graphical user session that will run `jarvisd`. A host command
such as `vulkaninfo` is insufficient if QVAC itself reports no device. Jarvis
will remain available for diagnostics but refuses inference until QVAC sees a
GPU.

## Voice doctor finds no wake engine

Install a local openWakeWord or sherpa-onnx bridge and set
`JARVIS_WAKE_COMMAND`. The bridge must read raw 16 kHz mono PCM from stdin and
write detected phrases, one per line, to stdout. Push-to-talk remains useful
for typed or manually triggered testing.

## Portal consent succeeds but input is unavailable

ScreenCast consent does not prove that RemoteDesktop/EIS injection is ready.
Configure `JARVIS_LIBEI_BRIDGE`; the helper intentionally fails closed without
it. Use observe-only mode until the injector reports ready. `ydotool` is an
optional, explicitly enabled fallback.

## The extension is missing

Check that `metadata.json` has UUID `jarvis@qvac.local`, copy the extension into
`~/.local/share/gnome-shell/extensions/jarvis@qvac.local`, then run:

```bash
gnome-extensions enable jarvis@qvac.local
journalctl --user -b | grep -i jarvis
```

## The daemon restarts

Inspect `journalctl --user -u jarvisd.service`. Common causes are Node version,
invalid QVAC config, missing session D-Bus, missing GPU visibility, or a stale
portal grant. Run the three doctor commands before changing model settings.

## Rolling release did not publish

Check the Gitea Actions log and repository secret name. It must be exactly
`RELEASE_TOKEN` with repository write permission. The workflow only publishes
from `main`; pull requests and other branches run CI but do not replace the
`rolling` prerelease.