> ## Documentation Index
> Fetch the complete documentation index at: https://keebye.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. On a Mac, Accessibility is granted in System Settings › Privacy & Security › Accessibility.
4. On a Mac, 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 your sound settings (System Settings › Sound on a Mac) 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 (Ctrl+V on Windows) or the keystrokes failed. The transcript is on your clipboard; paste it 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 (Mac)

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

### Windows SmartScreen says "Windows protected your PC"

The Windows installer is not code-signed yet. Choose More info, then Run anyway — only for an installer you downloaded from keebye.com.

### On Windows, dictation records nothing

Windows may be blocking microphone access for desktop apps. Open Settings › Privacy & security › Microphone, allow desktop apps to use the microphone, and check that the right input device is selected.

## Reset Keebye

Quit Keebye, delete settings.json (in ~/Library/Application Support/com.keebye.app/ on a Mac, %APPDATA%\com.keebye.app\ on Windows), and remove the stored credential for service com.keebye.app, account auth, from the macOS Keychain or Windows Credential Manager. Relaunch and onboarding starts again. Diagnostics go to stderr only.

> **Note:** Still stuck? Email hello@keebye.com with your macOS or Windows version and what the pill showed.