Skip to content
VoiceHotkeyVoiceHotkeyVoiceHotkey Docs

Troubleshooting

Pick a section by symptom and follow its checks in order. Figures are operation diagrams explaining troubleshooting paths and feature scope; your current app and macOS determine actual appearance.

Before you start: note these five

Section titled “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)

Hotkey does nothing

Section titled “Hotkey does nothing”

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

Checklist

Section titled “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

Section titled “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 Right Command, command Middle mouse button.
Operation diagram: Check paths and stale Accessibility entries
Check paths and stale Accessibility entries (operation diagram)

Recording but no text

Section titled “Recording but no text”

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

Checklist

Section titled “Checklist”
  • Microphone granted; correct input device
  • Engine ready (cloud credentials / Apple or local resources)
  • Local Only not blocking a cloud engine
  • Network / quota / key validity
  • Caret in a normal text field (secure fields may block insert)

Steps

Section titled “Steps”
  1. Recording readiness — new installations default to real ASR, and current Settings has no Demo switch. Check microphone access and input device. For legacy / test demo status, see First-time setup.
  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 — Check Settings → General → Output action. History-only is an internal mode not present in the current menu; it saves to history without insertion or automatic copying. Copy uses the clipboard. For insertion, select Insert at caret and focus an editable field. The default can copy when no editable focus is found. Try Notes if a terminal or secure field blocks injection.
Operation diagram: Use status messages to diagnose recording and output
Use status messages to diagnose recording and output (operation diagram)
Operation diagram: Local Only scope and license network exception
Local Only scope and license network exception (operation diagram)

Permissions keep resetting

Section titled “Permissions keep resetting”

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

Common causes

Section titled “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

Section titled “Fix”
  1. Keep a single app in Applications.
  2. Quit VoiceHotkey fully.
  3. Remove stale VoiceHotkey rows from Accessibility. Check the current app’s permission switch on Microphone.
  4. Launch from the fixed path and re-grant.
  5. Always open that same path instead of switching between installed copies.

Polish / translation unchanged

Section titled “Polish / translation unchanged”
  • Polish enabled / using the translation hotkey
  • Processing engine ready (cloud credentials / local model / Apple language resources)
  • Local Only not blocking the API
  • Polish failure may retain the original text; check History and status messages
  1. Settings → Text processing: polish on; translation uses its own hotkey.
  2. For cloud LLMs, check credentials, model, and endpoint; for local Spark, check installation. Apple native translation requires macOS 26+ and language resources, without an LLM key; it is unavailable on older systems.
  3. Local Only blocks public LLMs. Use an on-device model / loopback endpoint, or turn the mode off if appropriate. App-adaptive polish also requires Trial / Pro.
  4. Ensure raw voice typing works before enabling polish.

Voice commands do nothing

Section titled “Voice commands do nothing”
  • Settings → Voice commands → Enable voice commands is on
  • Command hotkey is registered and Accessibility is granted
  • The needed action capability is enabled, such as Allow hotkeys
  • User-dictionary entries are enabled and phrases match (exact then fuzzy)

There is no built-in phrase catalog; create and enable user entries. Free-form intent and selection rewrite require a Trial / Pro intent model. Window actions need Accessibility; reminders / events need the corresponding full access. See Voice commands.

Shell commands don’t run

Section titled “Shell commands don’t run”

The current version has no Shell execution, Allow Shell, Shell confirmation, or environment settings. Old Shell entries are unsupported. Changing Trial / Pro status or searching for removed controls cannot enable them. Use supported dictionary actions, prepared Shortcuts, or system control; see Shell command status.

License features locked or activation unavailable

Section titled “License features locked or activation unavailable”

Check the plan under Settings → License. Free includes basic polish and user commands, while intent, selection rewrite, adaptive polish, in-app file transcription, and custom history require Trial / Pro. The Activate Pro form appears on both Free and Trial; activated Pro uses Change key….

For a device-limit error, deactivate the old Mac while online. A failed unbinding request may leave the cloud seat occupied despite local deactivation. Network / server errors can fall back to local signature validation; explicit revoked / invalid / device-limit responses do not. See License & terms.

Operation diagram: Feature gates, activation access, and device seats
Feature gates, activation access, and device seats (operation diagram)

Quick scenarios

Section titled “Quick scenarios”
  1. Path + both permissions
  2. Check microphone and input device
  3. One working engine
  4. Test in Notes

Still stuck

Section titled “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 setupRecording readiness, engine, shortcuts, and test.