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

## Stylesheet parse `errcode:15`

GNOME Shell's St CSS parser rejects comments that contain `--`, `alpha(var())`,
and `icon-size`. If `journalctl` shows a stylesheet parse error on
`jarvis@qvac.local`, copy the current `stylesheet.css` into the live extension
directory and disable/enable the extension (GNOME 50 cannot `ReloadExtension`).
See [brand](brand.md).

## Settings window crashes on accent hex

GTK 4 `Gtk.Entry` has no `maxLength` constructor property. The hex field uses
`entry.get_buffer().set_max_length(7)`. If an older checkout still constructs
`maxlength`, Settings will abort when opening the Desktop page.

## Panel label shows “Jarv…”

The panel used to show the product name and a state chip at the same time,
which GNOME truncated. Idle is mark plus **Jarvis**; busy is mark plus one
state chip (Listening / Thinking / Speaking / Privacy). Never both.

## 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 enable `jarvis@qvac.local`. On GNOME 50 that
does not hot-reload; disable/enable the extension or log out if the panel is
still gone. 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.

## Browser tool says `no such file or directory`

`jarvisd` runs under Bare and starts a Node Playwright sidecar. Systemd user
services often do not have `node` on `PATH`, so spawn used to fail with that
message. Reinstall so `jarvisd.service` records `JARVIS_BROWSER_NODE`, then:

```bash
npm install
npm run browser:install
systemctl --user daemon-reload
systemctl --user restart jarvisd.service
```

To pin Node yourself:

```bash
systemctl --user edit jarvisd.service
```

Add `Environment=JARVIS_BROWSER_NODE=/usr/bin/node` under `[Service]`.

## The service reports `203/EXEC`

Current `jarvisd.service` starts packaged Bare, not `/usr/bin/node`. If
`ExecStart` still points at a missing `node` or Bare binary, re-run
`packaging/install.sh --enable` or the web installer. Check the result with:

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

## The daemon restarts

Inspect `journalctl --user -u jarvisd.service`. Common causes are a missing
Bare binary, invalid QVAC config, missing session D-Bus, missing GPU
visibility, or a stale portal grant. Run the three doctor commands before
changing model settings. Restarting `jarvisd` also clears an active desktop
grant.

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