Troubleshooting

Troubleshooting

Start here: agentwhisper status — every subsystem reports its health there, and most error messages contain their own fix. The full log is at ~/.local/state/agentwhisper/daemon.log.

Reading agentwhisper status

Line	Healthy value	If not
engine:	ready	loading = model still downloading (first run — wait). error: … = the message says what failed
hotkey:	f12 — grabbed (exclusive)	See "hotkey unavailable" below
desktop:	ok	Names the missing tool and the apt command
tray:	active	See "no tray icon" below
visualizer:	active	Install python3-gi-cairo, restart

No tray icon

sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1
cd agentwhisper && ./install.sh    # rebuilds the environment if needed

The app still works without the tray (control it with the agentwhisper command) — but on XFCE the icon should always appear.

"could not reserve 'f12'"

Another program holds a grab on exactly that key. With AgentWhisper not running, press F12 and see what reacts (drop-down terminals like Guake or Tilda are the usual suspects) — unbind it there, or give AgentWhisper a different key in the config (key = "scroll_lock").

Dictated, but no text appeared

1. agentwhisper status → engine: must be ready (loading = model still downloading, first run only)
2. desktop: must be ok — otherwise install the named tool
3. Taps under ~0.3 s are ignored on purpose; silence transcribes to nothing ("No speech detected" notification)
4. If typing failed, the text is still in your clipboard — Ctrl+V

"No speech detected" though you spoke

Test the microphone: arecord -d 3 test.wav && aplay test.wav. If you hear nothing, pick the right input device in your sound settings (AgentWhisper uses the system default input).

GPU (device = cuda) errors about cuDNN

CUDA mode needs cuDNN 9 for CUDA 12 installed. If in doubt, stay on the CPU defaults (device = cpu, compute_type = int8) — they are fast enough for the default model.

apt notice about "_apt" / sandbox when installing the .deb

Download is performed unsandboxed as root as file ... couldn't be
accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

Harmless. apt's sandbox user can't read files inside your home directory, so it falls back to fetching the local .deb as root; the installation itself is unaffected. To avoid the notice, install from /tmp:

cp dist/agentwhisper_*.deb /tmp/ && sudo apt install /tmp/agentwhisper_*.deb

Still stuck?

Attach the last lines of ~/.local/state/agentwhisper/daemon.log to a GitHub issue — every failure is logged with its stage and reason.