Troubleshooting

Troubleshooting & FAQ

Common symptoms and what to check, drawn from TypeWhisper's documented Linux behavior. If a control is disabled, the UI usually shows the reason and an install hint — read that first.

A control is disabled and shows a reason

Linux-specific checks disable unavailable controls and explain the missing tool. Depending on the feature you may be prompted to install one of:

Tool	Used for
pactl	Audio ducking
playerctl	Media pause during recording
pw-play / paplay / aplay	Sound feedback (PipeWire / PulseAudio / ALSA)
NVIDIA GPU + driver	The GPU backend — the CUDA 12 runtime libraries are downloaded on demand, so no toolkit install is needed

Install the named tool through your distribution, then revisit the setting.

The tray icon isn't showing on GNOME

GNOME Shell does not show AppIndicator/KStatusNotifier tray icons by default. Install and enable the AppIndicator extension:

sudo dnf install -y gnome-shell-extension-appindicator
gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com

If the enable command says the extension does not exist right after install, log out and back in, then enable again. Restart TypeWhisper afterward. See Wayland notes.

The global hotkey doesn't fire on Wayland

The evdev backend that makes the hotkey fire regardless of focus needs read access to keyboard event nodes. Use the Enable keyboard access action in Settings → Shortcuts (or the first-run setup) to install the keyboard uaccess udev rule — it applies to your active session immediately, no logout. On init systems without systemd-logind the rule falls back to input-group membership, which needs a re-login. Also confirm the backend is enabled in Settings → Shortcuts (it can be toggled off, which falls back to focused-only behavior). See Global hotkeys and Wayland notes.

Correction learning isn't learning anything

Learn corrections from other apps (Dictation) reads the focused field over AT-SPI, so it only works where the app publishes an accessibility tree.

1. Confirm the setting is on. It ships off by default.
2. Enable the accessibility bridge. Chromium/Electron apps (VS Code, browsers) and Qt apps only build an accessibility tree when the session flag org.a11y.Status.IsEnabled is on, and most desktops — GNOME included — leave it off. When the flag reads as off, an Enable accessibility bridge button appears on the Dictation page.
3. Restart the target app after enabling the bridge. Chromium/Electron apps read that flag only at launch; Qt apps pick it up immediately.
4. Check the app can expose text at all. Terminals, TUIs, and anything without an AT-SPI text interface are skipped silently — there is nothing to observe. This is expected and is deliberately kept out of the Error Log.

Learning is also intentionally conservative and will decline to learn from a password field (or any field whose role it can't determine), from an edit that changes your meaning rather than fixing a word, and from an edit that adds a line break.

Dictation stops working while the screen is locked

This is deliberate. While your login session is locked or inactive, TypeWhisper closes its keyboard readers, refuses to start a dictation (including through the HTTP API and CLI), aborts any recording already in flight, and suppresses text insertion. Everything resumes when you unlock. See Global hotkeys.

App-name / active-window matching isn't working

Profile matching by process name needs a window provider for your session:

• GNOME Wayland — install the Window Calls extension, then restart TypeWhisper.
• KDE Plasma — install kdotool; without it, app-name matching is unavailable in that session.

See Wayland notes and Profiles.

Browser URL profile rules aren't matching

URL rules read the browser's address bar, which on Wayland goes through AT-SPI:

1. Use the Enable browser URL detection button in the Profiles section.
2. For Firefox, also flip accessibility.force_disabled from 0 to -1 in about:config and restart Firefox (verify via about:support).
3. Check the Error Log on the About page for the AT-SPI walk diagnostic. matched-app=none means the browser isn't exposing AT-SPI; result=null with a non-null best-score means the walker reached the address bar but didn't recognize it.

See Wayland notes.

CUDA isn't loading

The GPU backend needs an NVIDIA GPU and driver. The CUDA 12 runtime libraries (libcudart.so.12, libcublas.so.12, …) are downloaded on demand: when a GPU is present but the runtime isn't cached, use the Download CUDA runtime button on the Dictation page, then restart TypeWhisper. The download is resumable, so an interrupted fetch picks up where it left off. If the libraries already exist on disk but aren't visible, use Fix CUDA path instead. CUDA applies to the bundled whisper.cpp and sherpa-onnx engines. See GPU & CUDA.

If CUDA was working and then stopped — the runtime fell back to CPU even though the libraries are cached — the cached runtime may be corrupt. A cached library is never re-verified once present, so use the Clear GPU runtime button on the Dictation page to delete it, then restart TypeWhisper to re-download a fresh copy. See GPU & CUDA.

Short or quiet clips are being dropped

A short-speech policy with peak-level and duration thresholds drops accidental taps and silent clips before they reach the engine. For short, quiet utterances you still want transcribed, turn on the aggressive short-clip transcription option. See Dictation.

Where the logs live

Logs are stored under Logs/ in the user data directory (~/.local/share/TypeWhisper on typical setups). The Error Log on the About page also records per-state AT-SPI walk diagnostics for URL detection. See Data and file paths.

Filing an issue

If you hit a setup-specific issue, please create an issue or pull request including your distribution, desktop environment, display server, reproduction steps, and any relevant logs (including the Error Log's AT-SPI walk diagnostics). See Contributing.

Related pages

• Wayland notes — the Wayland-specific causes behind most of these symptoms.
• GPU & CUDA — CUDA backend requirements.
• About — the Error Log and update checks.
• Data and file paths — where logs and data live.
• Contributing — how to file an issue or PR.

---

Changelog

Date	Change
2026-06-17	Initial version.
2026-06-17	Corrected the Sound feedback tool to pw-play / paplay / aplay (not canberra-gtk-play).
2026-06-23	v0.10.0: updated the hotkey FAQ for the keyboard uaccess rule and the CUDA FAQ for on-demand runtime download (Download CUDA runtime) plus sherpa-onnx support.
2026-06-24	v0.11.0: added corrupt-cache recovery (Clear GPU runtime) to the CUDA FAQ and noted that runtime downloads are resumable.
2026-07-27	v0.13.0: added FAQ entries for correction learning not learning (accessibility bridge, app coverage, the learning guards) and for dictation being stood down while the session is locked.