# 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

Fresh installs use the built-in CPU detector (`jarvis-wake-bridge`). If
`listeningMode` is Hold Talk only, or `wakeCommand` is empty, the detector is
disabled. A custom openWakeWord or sherpa-onnx 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

Grant desktop starts RemoteDesktop, then Jarvis connects to EIS with the
bundled libei sender. An external `JARVIS_LIBEI_BRIDGE` is optional. If input
still fails, run `npm run cu-doctor` and confirm `libei` is installed. Observation
does not need the injector: after a grant, `cu_observe` should return a screenshot
and accessibility tree even when pointer injection is down.

## The extension is missing

Preferences can open while the panel HUD is gone if the extension is installed
but not enabled in the running GNOME Shell. Re-run the installer so it copies
the HUD files and asks Shell to reload/enable `jarvis@qvac.local`. The
installer also keeps a copy at
`~/.local/share/gnome-shell/extensions/jarvis@qvac.local`:

```bash
curl -fsSL https://git.ssh.surf/snxraven/gnome-jarvis/raw/branch/main/packaging/web-installer.sh | bash -s -- --enable
```

Then confirm `metadata.json` has UUID `jarvis@qvac.local` and run:

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

If the extension still does not appear, log out and back in once so GNOME Shell
reloads its extension search path.

## The service reports `203/EXEC` for `/usr/bin/node`

Older installers wrote a fixed `/usr/bin/node` path. Re-run the current web
installer; it records the Node executable found in the installing user's PATH
when it writes the user service. Check the result with:

```bash
systemctl --user cat jarvisd.service | grep ExecStart
command -v node
```

## 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.