Troubleshooting

No audio detected

Check that your microphone is connected and selected as the input device
Grant microphone permission (macOS: System Settings > Privacy > Microphone)
Try a different audio input device in your OS sound settings
Enable debug mode (OPENWHISPR_LOG_LEVEL=debug in .env) and check audio level logs

Transcription fails or returns empty

If using local processing, make sure a model is downloaded (Settings > Speech Recognition)
Check that enough disk space is available for the model
If using cloud, verify your API key is valid and has credits
Try switching between local and cloud to isolate the issue

Text not pasting automatically

macOS — check Accessibility permission (System Settings > Privacy > Accessibility). Remove and re-add OpenWhispr if it’s already listed.
Linux X11 — install xdotool
Linux Wayland — install wtype or ydotool (with ydotoold daemon running)
All platforms — text is always copied to clipboard. Use Ctrl+V / Cmd+V to paste manually.

Hotkey not working

Check for conflicts with other apps using the same key
Try changing the hotkey in Settings
GNOME Wayland — hotkeys use native GNOME shortcuts. Check Settings > Keyboard > Shortcuts for conflicts. Default is Alt+R.
Hyprland — requires hyprctl on PATH

Meeting detection not working

Panel appears off-screen

Restart the app to reset the panel position. You can also drag it to a new location.

Local semantic search not working

Qdrant starts automatically on app launch. Check debug logs for “qdrant” entries.
If Qdrant fails, full-text keyword search still works as a fallback.
Manually download the embedding model: npm run download:embedding-model

Build issues

Debug mode