Troubleshooting¶
This page collects the real, documented problems users hit with YazSes and their exact fixes. Each entry is Symptom → Cause → Fix.
First: run yazses doctor¶
Before anything else, run the built-in health check. It diagnoses almost every problem on this page in one shot — missing audio library, input-group membership, injection backend readiness, which keyboard the hotkey binds to, whether the STT model is downloaded, a stale/duplicate install, and (with --mic) your microphone level versus the silence gate.
yazses doctor # full health check; act on any line that is not [OK]
yazses doctor --mic # also records a short ambient clip and checks it vs the VAD gate
Read the bottom-line verdict it prints:
✓ Everything looks good— you're set; hold the hotkey and dictate.▲ Good to go (… optional warnings)— dictation works; the warnings are optional.✗ N problems to fix— fix the[FAIL]lines above, then re-runyazses doctor.
If yazses quickstart looks more helpful, run that — it's a read-only, 3-step guide tailored to your machine and changes nothing.
See also: Install on Linux · Configuration reference.
Startup and installation¶
Daemon won't start / crashes immediately¶
Symptom — yazses start prints "started" but nothing works; the daemon is not actually running. yazses logs / journald show OSError: PortAudio library not found. yazses doctor shows the daemon as not running.
Cause — The libportaudio2 system library is missing. sounddevice loads it at import time, so the daemon aborts on startup. The APT .deb pulls this in automatically, but the pipx, uv tool, and snap paths do not — so a plain pip/pipx install can crash on first start while yazses start still reports success.
Fix — Install the library (and the rest of the runtime deps), then restart:
Or let yazses setup install every runtime dependency for you (safe to re-run):
yazses start / restart starts nothing (systemd 203/EXEC)¶
Symptom — yazses start or restart appears to succeed, but no daemon runs and the hotkey is dead. yazses doctor shows systemd unit: ExecStart=… does not exist.
Cause — A leftover systemd user unit points its ExecStart at a binary that no longer exists (a leftover from a different install method), so the service crash-loops with status 203/EXEC and swallows the start.
Fix — Point the unit at your real binary and reload:
which yazses-daemon # find the real path
# edit ~/.config/systemd/user/yazses.service so ExecStart=<that path>
systemctl --user daemon-reload
systemctl --user restart yazses
Multiple yazses installs / running stale code¶
Symptom — Fixes or upgrades don't seem to take effect. yazses doctor shows Install: multiple yazses on PATH ….
Cause — More than one copy is installed (e.g. apt and pipx and uv tool). An upgrade can leave you running an older copy.
Fix — Keep one, remove the rest:
The hotkey does nothing¶
Keyboard capture fails — not in the input group¶
Symptom — Holding the key records nothing (no transcript, no overlay). yazses doctor reports [FAIL] Keyboard capture: denied.
Cause — The hold-to-talk hotkey is read directly from the kernel input devices (/dev/input/event*), which are owned by the input group. If your user isn't in that group the daemon cannot see the hotkey.
Fix — Join the group, then log out and back in (or reboot):
sudo usermod -aG input "$USER"
# now LOG OUT and back in — a new terminal tab is NOT enough
id -nG | tr ' ' '\n' | grep -x input # should print: input
yazses doctor # should show [OK] Keyboard capture
The re-login is mandatory and one-time — group membership only refreshes in a new login session; opening another terminal tab inherits the old session's groups and the hotkey stays dead. To dictate immediately without logging out, bridge the group for one session:
After a real re-login, a plain yazses start just works — no bridge needed. See Install on Linux §3b.
Hotkey bound to a virtual device¶
Symptom — Keyboard capture looks granted, but the hotkey still does nothing. yazses doctor reports Hotkey device: bound to virtual device … (e.g. ydotoold virtual device).
Cause — The daemon bound to an injector's virtual uinput device instead of your real keyboard. That device only ever carries synthetic events, so your real keypresses are never seen. This tends to appear after yazses setup provisions ydotoold.
Fix — Ensure your real keyboard is readable (you are in the input group, per the previous entry) and upgrade YazSes. v1.3.3+ skips virtual/injection devices automatically and prefers a full keyboard; older builds need the upgrade:
pipx upgrade yazses # or: uv tool install --force <path> / apt upgrade
yazses restart
yazses doctor # Hotkey device should now name your real keyboard
First word(s) of dictation lost¶
Symptom — The beginning of what you say is clipped — the first one to three words don't get transcribed.
Cause — A short lead-in of silence is prepended before decode so faster-whisper doesn't clip the onset. If that padding is too short for your speaking style, the first word can still be lost.
Fix — Increase the pre-speech padding in ~/.config/yazses/config.toml (default 300 ms), then restart:
(Dysfluency-Friendly Mode already widens this onset padding automatically when enabled.)
Nothing gets typed (injection fails)¶
No text appears after you speak¶
Symptom — Transcription happens (you may see the overlay react), but no text lands in the focused app. yazses doctor shows an Injection line that is not [OK].
Cause — The right injection backend for your session isn't available or running. How text gets typed depends on the session type:
| Session | Injector | Notes |
|---|---|---|
| X11 | xdotool | works out of the box |
| Wayland — wlroots (Sway, Hyprland, …) | wtype | works out of the box |
| Wayland — GNOME / KDE | ydotool + a running ydotoold | wtype is blocked by Mutter/KWin; ydotool is the only reliable option |
On GNOME/KDE Wayland, ydotool also needs the ydotoold daemon running, or it fails with failed to connect socket … .ydotool_socket.
Fix — Let yazses setup install and enable the correct backend (including ydotoold on GNOME/KDE Wayland):
To set it up by hand on GNOME/KDE Wayland, enable the ydotoold user service — see Install on Linux §3c.
xdotool present but injection fails (missing libxdo.so.3)¶
Symptom — On X11, nothing is typed even though xdotool is installed. yazses doctor warns that xdotool is present but not runnable (missing libxdo.so.3).
Cause — The xdotool binary is on PATH but its shared library (libxdo.so.3) is missing — every type() exits with a loader error and injection silently fails (common in a broken/partial bundle).
Fix — Reinstall/upgrade the package so the library is present:
Clipboard backend types nothing in a terminal¶
Symptom — With [injection] backend = "clipboard", dictation works in GUI apps but a terminal receives nothing (or a literal ^V), and your clipboard gets overwritten.
Cause — The clipboard backend pastes with Ctrl+V. In a terminal Ctrl+V is literal (not paste), so it's a no-op there, and it overwrites whatever you had copied.
Fix — Use the default auto backend, which types the text (works everywhere, terminals included) and never touches the clipboard:
backend values: auto (recommended), xdotool/ydotool/wtype to force a specific typing backend, or clipboard only when you specifically want paste.
Audio and recognition¶
Silent audio -- discarding in the logs¶
Symptom — Dictation does nothing. yazses logs shows Silent audio -- discarding.
Cause — Your speech fell below the VAD (voice-activity) gate — the daemon treats the recording as silence and drops it. The gate compares the mean absolute audio level against accessibility.vad_threshold.
Fix — Measure your voice and write a fitting threshold, then restart:
Lower vad_threshold for quiet speech; raise it if room noise triggers spurious transcripts. Re-run whenever your speaking volume changes (e.g. quiet late-night dictation). You can also edit it directly:
yazses doctor --mic warns when your resting room level already meets or exceeds the threshold (which would leak noise through as spurious transcripts).
Dictation stopped after plugging in a monitor / dock / headset¶
Symptom — Dictation was working, then stopped writing after you connected a USB-C monitor, a docking station, or a headset. It may have worked for a while first. yazses logs shows repeated Silent audio -- discarding.
Cause — Capture follows the OS default input device. Plugging in a monitor or dock that carries an audio endpoint can make PulseAudio/PipeWire silently re-pick that as the default input — usually a dead or very quiet source — so every clip falls below the VAD gate and is discarded. Nothing crashes; the OS just switched your mic out from under the daemon (and it often only flips a little while after you plug in, which is why it "worked for a moment").
Fix — See which mic is in use and pin your real one:
yazses audio status # pinned vs OS-default mic + live capture health
yazses audio devices # ● = OS default, ★ = pinned
yazses audio use "AT Translated" # pin your built-in/real mic by name (substring)
yazses restart
The mic-change guard (on by default) also catches this automatically: it notices the device change / run of silent clips, auto-heals by switching capture back to the last mic that worked, and pops a desktop notification with Re-calibrate / Pin this mic / Ignore buttons. Turn it off with yazses features disable mic-guard if you don't want the notifications.
I dictated but nothing was typed (no text field focused)¶
Symptom — You hold the key, the sonar/tray shows you're recording, you speak and release — but no text appears. The tray icon was yellow (not green) while you spoke.
Cause — There was no editable text field focused, so there was nowhere to type. This is the most common "it heard me but typed nothing" case: you need to click into a text box before dictating.
What YazSes does — With the text-target guard (on by default), instead of typing into the wrong place it turns the tray icon yellow and copies your dictation to the clipboard + notifies you. Click into a text field and paste with Ctrl+V — your words aren't lost. Fix it going forward by clicking into the field first.
For precise detection (so it also catches "app focused but no field", not just "no window at all"), install the accessibility bridge:
yazses doctor shows whether the guard is running in AT-SPI (precise) or best-effort mode. Change the behaviour with [injection] target_guard (clipboard default | warn — notify but still type | off), or yazses features disable target-guard.
Tray icon doesn't appear in the top bar¶
Symptom — yazses tray runs (or the daemon started) but no microphone icon shows in the top bar. The log says No system tray is available on this desktop.
Cause — The desktop has no StatusNotifier/AppIndicator host. GNOME does not show tray icons out of the box; it needs the AppIndicator extension. (Ubuntu ships and enables it by default, which is why it works there.)
Fix — Install/enable an AppIndicator extension:
# GNOME (non-Ubuntu): install the extension, then enable it
sudo apt install gnome-shell-extension-appindicator # Debian/Ubuntu package name
gnome-extensions enable ubuntu-appindicators@ubuntu.com # or appindicatorsupport@rgcjonas.gmail.com
# log out/in (or restart GNOME Shell) so the extension loads, then:
yazses tray
Everything the tray does is also available from the terminal (yazses audio use <name>, yazses mic-level --set, yazses restart), so the tray is a convenience, not a requirement. Turn off auto-launch with yazses features disable tray.
STT model not downloaded¶
Symptom — The first dictation stalls or a model download runs unexpectedly. yazses doctor shows STT model … not downloaded.
Cause — The configured faster-whisper model isn't in the local cache yet. It is fetched automatically on first dictation, which needs a network connection once.
Fix — Trigger it once with a network connection (dictate once, or start the daemon and hold the hotkey briefly). After that it runs fully offline. Re-run yazses doctor — the model should show (cached).
Double typing (everything appears twice)¶
Symptom — Each dictation is typed twice.
Cause — Two daemons are running and both react to the hotkey — typically a detached yazses start surviving alongside a systemd-managed instance.
Fix — Stop every daemon (including detached ones) and start exactly one:
If you manage the daemon with systemd, use systemctl --user restart yazses instead of mixing it with a detached yazses start — mixing the two can leave two daemons fighting over the hotkey (or none running at all).
Snap-specific limits¶
Hold-to-talk never fires on the snap¶
Symptom — Installed via sudo snap install yazses, but the hotkey never triggers dictation, no matter what yazses doctor says about the input group.
Cause — The snap runs under strict confinement, which blocks reading the raw kernel input devices (/dev/input). Hold-to-talk cannot work from the confined snap — only the offline yazses transcribe <file> path does.
Fix — Install unconfined instead (APT script or pipx/uv tool), which capture the hotkey:
# APT (Debian/Ubuntu) — pulls in all runtime deps:
bash <(curl -fsSL https://raw.githubusercontent.com/MSKazemi/yazses/main/install-apt.sh)
# or pipx (any distro, Python ≥ 3.11):
pipx install yazses
# or from a source checkout with uv:
uv tool install --force /path/to/yazses
Snap microphone not granted¶
Symptom — On the snap, yazses doctor reports the microphone as not granted, or nothing records.
Cause — Strictly-confined snaps can't self-connect interfaces, and the audio-record interface is not auto-connected. It stays disconnected until you connect it once.
Fix — Connect it once (a one-time step):
macOS and Windows¶
macOS — nothing types / mic denied¶
Symptom — On macOS, dictation is transcribed but nothing is typed, or the mic never records.
Cause — macOS gates keystroke injection behind Accessibility and recording behind Microphone permission. Both must be granted to YazSes.
Fix — Grant them in System Settings, then restart the app:
- Accessibility — System Settings → Privacy & Security → Accessibility → enable YazSes. Shortcut:
- Microphone — approve the prompt on first record, or enable YazSes under Privacy & Security → Microphone.
On unsigned developer-preview builds, Gatekeeper blocks the first launch: right-click the app → Open, then grant the permissions above.
Windows — SmartScreen blocks the app¶
Symptom — On Windows, launching the app shows a SmartScreen warning and it won't start.
Cause — v0 builds are unsigned, so SmartScreen flags them.
Fix — Click More info → Run anyway. If antivirus quarantines the executable, add an exception for it. See Install on Windows.
Gaze / Glance-Type (look-to-pane)¶
Full setup is in Aim dictation with your gaze; these are the common snags. Run yazses gaze status first — every line should be a ✓.
can't open camera by index / 0 point(s) captured a face when calibrating¶
Cause — Something else is holding the single webcam, almost always the running YazSes daemon (it uses the camera at hold-time when gaze is on), or a video call / browser tab.
Fix — Stop the daemon, then calibrate, then start it again:
If your webcam is not index 0, set [gaze] camera_index in config.toml.
Dictation ignores my gaze — always types into the same window¶
Cause — Usually calibration that does not discriminate between screen regions. Confirm what the router is choosing:
If the window id changes as you look left vs right, gaze is working — line up your windows in clearly different halves of the screen. If it is the same id every time, re-calibrate carefully (deliberate eye movement to each point, head still, good lighting):
Nothing routes at all¶
Cause — Glance-Type is X11-only (Wayland forbids focusing other apps' windows), or the webcam deps / calibration are missing.
Fix — Check echo $XDG_SESSION_TYPE; if it says wayland, log in with an Xorg / X11 session. Otherwise run yazses gaze status and fix any ✗ line (yazses features enable gaze --force installs the deps; yazses gaze calibrate creates the calibration).
Still stuck?¶
Re-run yazses doctor and read the bottom-line verdict — it points at the exact next command. If a problem persists, the doctor output prints the author's contact and the issue tracker; include the full yazses doctor output and the tail of yazses logs when reporting.