# Yappy troubleshooting

Almost every Yappy problem is a macOS permission problem wearing a disguise.

## The hotkey does nothing

**Cause:** Accessibility is not granted, or was granted after launch.

macOS reads the Accessibility grant when the app starts and does not re-read it
live. So the sequence that works is: enable it, then **quit and relaunch Yappy**.

**System Settings → Privacy & Security → Accessibility → Yappy → on**, then quit
Yappy from the menubar and open it again.

If Yappy is already listed and enabled but the key still does nothing, remove the
entry with the minus button, relaunch, and let it re-add itself. macOS keeps the
grant keyed to the app's signature, and a rebuilt or re-downloaded copy is a
different signature to it.

## Dictation records but nothing is typed

The transcription worked and the insertion did not. Two usual causes:

- **No editable field is focused.** Click into the text field first.
- **The target app blocks synthetic paste.** Some secure fields do, by design.
  Password fields will never accept dictated text.

## It hears silence

Check **System Settings → Privacy & Security → Microphone → Yappy**. If the
permission is on and Yappy still hears nothing, check the input device in
**Sound** — a disconnected headset that macOS still lists as the input is the
common culprit.

Dictation in a noisy room is a different problem: voice isolation is on by
default, and upgrading to `large-v3-turbo` helps more than anything else. See
[dictation](https://yappy.biz/docs/dictation).

## The lid is closed / clamshell mode

With the lid shut and an external display attached, the built-in microphone is
unavailable. Yappy warns rather than silently recording nothing. Use an external
mic or open the lid.

## Agent Mode does not start

Agent Mode needs the `claude` CLI, separately from your cleanup backend:

```bash
which claude || curl -fsSL https://claude.ai/install.sh | bash
claude          # sign in, then /exit
```

If `claude` is installed somewhere other than `/opt/homebrew/bin/claude`, Yappy
corrects `claudeBin` at launch — but a relaunch is what triggers that.

## Dictation is slow

The cleanup backend is almost always the reason. `claudeCode` is 4–6 seconds by
nature; `ollama` is 1–3; the hosted plan is under one. See
[backends](https://yappy.biz/docs/backends). Turning AI Cleanup off removes the
step entirely and pastes the raw transcript instantly.

## Text arrives with a stray dash

Fixed in the transcript filter — subtitle-style dialogue in the training data
made Whisper start lines with a dash. Update to the current version. If you see
it mid-sentence rather than leading, mail **support@yappy.biz** with the sentence;
that variant is still being tracked.

## Updates are not arriving

`autoUpdate` is on by default and checks a signed appcast, verifying the
publisher's Apple team ID before installing. If your network blocks the R2
endpoint, download the current `.dmg` from
[yappy.biz/download](https://yappy.biz/download) and drag it over the old copy —
settings and models are kept.

## Still stuck

Menubar → **Send Feedback** attaches the app version, macOS version, and the
recent log tail, which turns a two-day exchange into one message. Or write to
**support@yappy.biz** directly.

---

Canonical: https://yappy.biz/docs/troubleshooting/ · Last updated: 2026-08-25