Skip to documentation content
Keebye Docs

Troubleshooting

What each message Keebye shows means and how to fix it, plus how to reset.

Most problems come down to a permission, a missing model, or dictation being paused. Start with the quick checks, then find your message below.

Hotkey does nothing? Check these first

  1. "Enable Dictation" is checked in the tray menu.
  2. You are signed in and the trial has not ended (Settings › Account).
  3. Accessibility is granted in System Settings › Privacy & Security › Accessibility.
  4. No secure input is active — for example Secure Keyboard Entry in Terminal, or a focused password field.

Messages and what they mean

"Accessibility permission was revoked — reopen System Settings"

Accessibility trust was missing when recording started. Open System Settings › Privacy & Security › Accessibility and switch Keebye on. Keebye re-arms the hotkey within 2 seconds.

"Failed to start the global hotkey listener"

macOS refused the event tap. Grant Accessibility access, then pick your key again in Settings.

"Could not arm <Key> — grant Keebye Accessibility access, then pick it again." or "Could not switch to <Key>; still using <Key>."

Changing the hotkey was refused. Grant Accessibility access and choose the key again; Keebye keeps using the previous key until then.

"Microphone capture failed: <error>"

There is no default input device or the audio stream failed. Check the input device in System Settings › Sound and that Microphone access is granted.

"Speech model still setting up — try again in a moment"

The selected model is not on disk or has not finished loading. Wait for the pill to leave the download state, or press "Download model" in Settings › Speech engine.

"Model download failed — reopen Keebye to retry"

Five download attempts failed (network, HTTP error, or checksum mismatch). Quit and reopen Keebye; the download resumes from where it stopped.

"Speech Recognition permission needed — enable Keebye under System Settings › Privacy & Security › Speech Recognition"

The Native (Apple Speech) engine is selected without authorization. Grant Speech Recognition, or switch to Parakeet or Canary.

"Apple Speech recognizer is not available for locale …", "Apple Speech recognized no speech", or "Apple Speech timed out after 15s"

Native engine issues. The on-device language model may need to be installed via System Settings › Keyboard › Dictation; otherwise speak within 15 seconds or switch engines.

"Couldn't insert: Secure input is active (<App>) — dictation is blocked" or "Couldn't insert: A password field is focused — dictation is blocked"

A password field is focused or an app has Secure Keyboard Entry on (Terminal, for example). Click into a normal text field or turn off Secure Keyboard Entry. This is by design.

"Text left on clipboard — paste manually"

Synthesizing ⌘V or the keystrokes failed. The transcript is on your clipboard; press ⌘V yourself.

"Dictation hit an internal error and was reset. Please try again."

The session worker recovered from a crash. Dictate again.

The onboarding window reopened after an update or reinstall

A stale Accessibility grant. Remove Keebye from System Settings › Privacy & Security › Accessibility with the − button, add it back, and switch it on.

Reset Keebye

Quit Keebye, delete ~/Library/Application Support/com.keebye.app/settings.json, and remove the Keychain item for service com.keebye.app, account auth. Relaunch and onboarding starts again. Diagnostics go to stderr only.