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

# Troubleshooting

> Solutions to common issues with OpenWhispr.

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Hotkey not working">
    * Check for conflicts with other apps using the same key
    * Try changing the hotkey in Settings, or click **Add another hotkey** to bind a second key as a fallback
    * **GNOME Wayland** — hotkeys use native GNOME shortcuts. Check Settings > Keyboard > Shortcuts for conflicts. The default fallback is `F8`.
    * **Hyprland** — requires `hyprctl` on PATH
  </Accordion>

  <Accordion title="Meeting detection not working">
    * **macOS** — grant Screen Recording permission
    * Make sure Google Calendar is connected in Integrations
    * Check that meeting detection is enabled in Settings
    * Enable debug mode and look for "event-driven" vs "polling" in the logs
  </Accordion>

  <Accordion title="Panel appears off-screen">
    Restart the app to reset the panel position. You can also drag it to a new location.
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="Build issues">
    * Use Node.js 24 (pinned in `.nvmrc`)
    * Run `npm run pack` for unsigned builds (no certificates needed)
    * Run `npm run download:whisper-cpp` before packaging
    * If Electron reports that it failed to install correctly, run `npm config set ignore-scripts false`, then `npm rebuild electron`
    * See the [contributing guide](/contributing) for detailed build instructions
  </Accordion>
</AccordionGroup>

## Debug mode

Enable detailed logging by setting `OPENWHISPR_LOG_LEVEL=debug` in your `.env` file or launching with `--log-level=debug`. Logs are saved to your platform's app data directory.

## Getting help

* [GitHub Issues](https://github.com/OpenWhispr/openwhispr/issues) — report bugs or request features
* Check the console logs for error details