Troubleshooting

Pick a section by symptom. Each has a checklist and ordered fixes. Settings shots (ts-03/ts-04) and system/menu-bar shots (ts-01/ts-02) are UI-replica WebP images (regenerate with make docs-screenshots).

Before you start: note these five

1. macOS version
2. VoiceHotkey version (Settings → About)
3. Recognition engine name
4. Local Only on/off
5. App path (Finder → Get Info)

Privacy

Never paste API keys, license secrets, or sensitive transcripts. See Contact.

---

Hotkey does nothing

No overlay, no menu-bar status change, no system feedback.

Checklist

• Menu bar icon present (app running)
• Accessibility enabled for the current app path
• Launched from /Applications or ~/Applications
• Hotkey not conflicting with another app
• Hotkey page not warning about Accessibility

Steps

1. Process — Menu bar icon should open a menu. Relaunch from Applications if missing.
2. Accessibility — System Settings → Privacy & Security → Accessibility. One VoiceHotkey row, correct path, switch on. Remove duplicates, quit and reopen the app.
3. Stable path — See Install & permissions.
4. Rebind — Settings → Shortcuts → record a less common chord.
5. Conflicts — Quit tools that clash with defaults: dictation ⌃⌥Space, command ⌃⌥C.

Fig. A · Accessibility list (UI preview · ts-01-accessibility-list.webp)

---

Recording but no text

Overlay shows listening, but the field stays empty or processing never finishes.

Checklist

• Demo mode off
• Microphone granted; correct input device
• Engine configured (key / Apple ready)
• Local Only not blocking a cloud engine
• Network / quota / key validity
• Caret in a normal text field (secure fields may block insert)

Steps

1. Settings → General — turn Demo mode off.
2. Read menu bar status — mic needed, engine not configured, Local Only blocked, etc.
3. Microphone — enable for VoiceHotkey; verify hardware with Voice Memos.
4. Engine — try Apple as a control. If Apple works but cloud fails → key/network/quota.
5. Local Only — public engines fail when Local Only is on.
6. Output — Text processing Output action should insert at caret; try Notes if Terminal blocks injection.

Fig. B · Menu bar status (UI preview · ts-02-menubar-status.webp)

Fig. C · Local Only (UI replica · ts-03-local-only.webp)

---

Permissions keep resetting

Worked yesterday; hotkey dead today; Accessibility looks half-set.

Common causes

Cause	Notes
Path changed	Downloads, another folder, or a different build path
Signature / replace	Overwrite install treated as a new app
Duplicate rows	Wrong Accessibility entry bound

Fix

1. Keep a single app in Applications.
2. Quit VoiceHotkey fully.
3. Remove all VoiceHotkey rows from Accessibility and Microphone.
4. Launch from the fixed path and re-grant.
5. Always open that same path (debug vs release packages count as different paths).

---

Polish / translation unchanged

• Polish enabled / using the translation hotkey
• Post-process LLM key configured
• Local Only not blocking the API
• Fallback may insert raw transcript (expected on failure)

1. Settings → Text processing: polish on; translation uses its own hotkey.
2. Configure LLM provider keys.
3. Compare with Local Only off, or point Base URL at localhost.
4. Ensure raw voice typing works before enabling polish.

---

Voice commands do nothing

• Settings → Voice commands → Enable voice commands is on
• Command hotkey is registered and Accessibility is granted
• Allow hotkeys is not turned off (if you only use dictionary shortcuts)
• User-dictionary entries are enabled and phrases match (exact then fuzzy)

See Voice commands.

---

Shell commands don’t run

• Enable voice commands master switch is on
• Trial or Pro (not Free)
• Settings → Voice commands → Allow shell commands enabled (not under General)
• Didn’t cancel the confirm dialog
• Not blocked by the danger blocklist
• For intent-generated shell: intent model on and configured; for dictionary shell: entry type is shell and enabled

See Shell commands and Plans.

Fig. D · License (UI replica · ts-04-license.webp)

---

Quick scenarios

Fresh install

1. Path + both permissions
2. Demo mode off
3. One working engine
4. Test in Notes

After upgrade

1. Launch the new build from Applications
2. Clear stale Accessibility rows and re-grant
3. Confirm About version

Work network / privacy

1. Cloud APIs must be reachable
2. Or use Apple, the four on-device engines, or localhost
3. Local Only also pauses update checks

---

Still stuck

1. Re-run the first-setup dry run.
2. Collect the five items at the top.
3. File an issue via Contact.

Install & permissionsDMG, path, Accessibility, microphone.

First-time setupDemo mode, engine, hotkeys, test.