troubleshooting.md

title	YazSes troubleshooting — dictation not working, no text, mic issues
description	Fixes for the most common YazSes problems — hotkey not firing, no text appearing, silent audio discarded, microphone switching, and Wayland text injection.

Troubleshooting

Start here: prove where it breaks

Before reading further, let YazSes tell you which part is broken:

yazses verify     # records you, then runs capture → silence gate → transcription → cleaning

It reports each link in the chain and stops at the first failure, so you get the one thing to fix rather than four symptoms of it. yazses doctor complements it by checking prerequisites — a mic exists, the injector is installed, the model is cached — but every one of those can pass while dictation still produces nothing, which is why verify exists.

If you want to report a problem, yazses report writes a diagnostic file locally — versions, daemon state, settings with paths and identifiers removed, and the metadata-only log tail. Your dictated text is never in it, and nothing is uploaded; the file is yours to read before deciding to attach it to an issue.

YazSes usually tells you first

Most failures now announce themselves as a desktop notification that names the cause and the command that fixes it — a microphone another program has taken, a missing ydotool, a full disk. So the first thing to do is read the message rather than start here.

Two details worth knowing:

• The same problem is announced once every five minutes, not once per attempt. A microphone that will not open fails on every burst, and repeat toasts would only teach you to dismiss them. The state is still in yazses status and the tray tooltip throughout.
• When YazSes cannot work out what went wrong, the notification carries a Prepare a bug report button. It assembles the same redacted bundle yazses report writes and opens GitHub's issue form with it filled in — you read it there, in your own browser and account, and press submit yourself. YazSes sends nothing; the browser makes the request. A failure YazSes does recognise gets no button, because it already told you the fix.

!!! tip "Some of this fixes itself — check before you debug"

A microphone that was stolen mid-session, a silence gate that drifted above
your voice, a crashed daemon and a crashed tray all recover on their own, and
each says so when it happens. If you are about to debug one of those, read
**[what recovers by itself, and what does not](reliability.md)** first — it
also lists the failures that are deliberately left for you, so you can tell
which kind you are looking at.

It works, but not after I reboot

YazSes is a daemon, so it should already be running when you sit down:

yazses autostart status   # will it come back after the next reboot?
yazses autostart enable   # make it

Installing with pipx, uv tool or pip does not set this up on its own. yazses doctor reports it as a Starts at login check.

Dictation stopped working right after I edited config.toml

If every hold is accepted but no text ever appears, read the log first:

yazses logs

A line like this means the pipeline threw an exception on every burst:

WARNING yazses.core.daemon: Pipeline error: ufunc 'less' did not contain a loop
with signature matching types (Float32DType, StrDType) -> None

Float32DType is your audio, StrDType is a config value that should have been a number. The usual cause is a quoted number in config.toml:

[accessibility]
vad_threshold = "0.004"   # wrong — this is a string
vad_threshold = 0.004     # right — bare number

In TOML, only string values take quotes. Numbers (int, float) and booleans must be bare, and the Configuration Reference lists the expected type for every key. A quoted number loads without any error and only fails later, deep in the pipeline, so the message never mentions the file you edited.

The safe way to change a setting is to let YazSes write it, since these commands always emit the right type:

yazses features enable <name>    # feature toggles
yazses hotkey set right_ctrl     # hold-to-talk key
yazses audio use "<mic name>"    # input device
yazses mic-level --set           # measure and write vad_threshold

Dictation still works, but it behaves differently than it used to

Every setting that affects the pipeline is announced when the daemon starts, so the log is an accurate record of what was actually in effect — including on previous days.

yazses logs -n 25          # this run's startup banner

A healthy start looks roughly like this. Each line reflects a config value, so a line that is present, missing, or different from what you remember tells you exactly which setting changed:

Loading STT model 'base.en'...          ← [stt] model
Injection backend: XdotoolInjector      ← [injection] backend
Streaming STT enabled (partial …)       ← [streaming] enabled  (absent when off)
Command key enabled: hold right_alt …   ← [hotkey] command_key (absent when unset)
YazSes ready. Hold right_ctrl to dictate.  ← [hotkey] key
Launched voice-activity overlay …       ← [overlay] enabled

To compare against a day when it behaved the way you wanted, look at the rotated log, which keeps the previous startups:

grep -h "YazSes ready\|Streaming STT\|Command key\|Loading STT model" \
  ~/.local/state/yazses/log/daemon.log.1 ~/.local/state/yazses/log/daemon.log

Two settings are worth checking first, because both change how dictation feels without ever producing an error:

• [streaming] enabled = true runs a transcription pass every 300 ms during the hold, on top of the final one. On a CPU-only machine that competes with the transcription that actually produces your text. It is off by default for this reason.
• [accessibility] vad_threshold decides what counts as silence. Too high and quiet speech is dropped with Silent audio -- discarding; too low and room noise is transcribed. It is specific to your microphone and room — run yazses mic-level --set rather than copying a value from someone else.

YazSes typed a sentence I never said

Speech models do not return "I heard nothing". Given near-silence they return their best guess at what a person would have said, and that guess is ordinary, fluent English — not gibberish you could spot. YazSes filters the recognisable cases (a blank marker, a caption artefact, a phrase repeating in a loop) but an invented sentence is indistinguishable from a real one to everything except you.

What makes it happen is a silence gate set below your room, so the noise floor is treated as speech and sent to be transcribed. Check it:

yazses verify

If the Signal line ends with "but only just" and a multiple close to 1, that is the cause. Your voice should sit several times above the gate; noise sits just over it.

yazses mic-level --set   # measure this room, write the threshold
yazses restart

Then run yazses verify again in a quiet room without speaking. The outcome you want is verify failing at either Signal or Speech — the model being given nothing is the only reliable way to stop it inventing. Speech is the one that fires when room noise clears the gate: it runs a speech detector on what was actually recorded, so a quiet room is named as a quiet room rather than transcribed into a confident word.

Raising the gate too far has the opposite failure and it is the visible one: quiet speech is dropped with Silent audio -- discarding in yazses logs. That is why the automatic tuner only ever lowers the gate — a mic that hears too little tells you so, and a mic that hears too much does not.

Dictation stops after connecting a USB-C monitor or headset

Some monitors, docks, and headsets register an audio input and become the operating system's default microphone. When that input is silent or very quiet, YazSes can keep running but stop writing dictated text because each recording is discarded as silence.

Check which device YazSes is using:

yazses audio status
yazses audio devices

The mic-change guard normally detects a default-input change and switches back to the last working microphone. To prevent the operating system from changing the capture device again, pin the intended microphone using a case-insensitive part of its displayed name, then restart YazSes:

yazses audio use "Built-in Microphone"
yazses restart

Run yazses audio status again to confirm that the pinned microphone is active. To return to following the operating system default later, run:

yazses audio use --clear
yazses restart