Troubleshooting

Pick a section by symptom. Each has a checklist and ordered fixes. Dashed frames are screenshot placeholders (public/screenshots/ts-*.svg).

Before you start: note these five

1. macOS version
2. VoiceHotkey version (Settings → About)
3. Dictation 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 → Hotkey → record a less common chord.
5. Conflicts — Quit tools that clash with defaults: dictation ⌃⌥Space, command ⌥Space.

Fig. A · Accessibility list (placeholder · ts-01-accessibility-list.svg)

---

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 — post-process Output action should insert at caret; try Notes if Terminal blocks injection.

Fig. B · Menu bar status (placeholder · ts-02-menubar-status.svg)

Fig. C · Local Only (placeholder · ts-03-local-only.svg)

---

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 post-process: 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 bare dictation 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 (placeholder · ts-04-license.svg)

---

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 / 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.