Troubleshooting

Try a short recording with the in-app button before testing shortcuts, auto-paste, or optional AI features. That makes it easier to identify which part of the workflow needs attention.

The app will not open#

Confirm that the installer matches your platform and architecture. Native macOS packages require Apple Silicon and macOS 14+; Intel Macs use a source installation.

Verify the download and follow your platform's first-launch steps in Installation. Release 2.6.14 fixes packaged startup failures involving missing lazy Qt widgets; if you see an import error such as ui_qt.widgets.tabbed_content, update the app.

The microphone is silent#

Check Settings → Recording and select the intended microphone. Confirm that the microphone works in another recording app and that your operating system permits OpenWhisper to use it.

On macOS, allow Microphone in System Settings → Privacy & Security. Try Quick Record again with the in-app button.

A model or runtime is missing#

Open Settings → Downloads and check the selected model's required components. Optional engines need both their model weights and a compatible runtime.

If you are offline, reconnect to install the missing component or select a model already downloaded. Check the missing-model download policy in Downloads if installation is blocked.

GPU acceleration is unavailable#

Check the engine's platform support in Choosing a model. Local Whisper on macOS uses CPU; its NVIDIA GPU Acceleration component is for supported Windows and Linux systems.

Other engines use separate runtimes. On Apple Silicon, install the runtime appropriate to the selected engine. Try CPU to verify transcription while investigating a GPU configuration issue.

Hotkeys or auto-paste do not work#

Confirm the shortcuts in Settings → Hotkeys. Choose a shortcut your keyboard can produce and check for conflicts with other apps.

On macOS, auto-paste needs Accessibility permission. Open Settings → General → Set up auto-paste and allow the identified app. If an update broke permission, remove the old entry, add the app again, and restart. Global hotkeys do not require Accessibility.

On Linux, X11 supports global hotkeys and auto-paste. Omarchy has supported desktop integration; other native Wayland desktops use focused-window shortcuts and manual paste. Keep using the recording button and clipboard copy while resolving shortcut issues.

Meeting system audio is missing#

On macOS, allow Screen & System Audio Recording. Run a short test with audio playing and confirm the selected output device.

Linux needs PulseAudio or PipeWire-Pulse and a validated monitor for the default output. Use the app's readiness dialog and Retry detection, then follow the Linux audio diagnostics for the exact error key. Linux meeting capture remains a preview.

AI cleanup or insights fail#

Check the selected provider, endpoint, text model, API key, and network connection. Custom endpoints must use the API your server supports: Chat Completions or Responses.

Cleanup failures preserve the raw transcript. For meeting insights, install or update the selected agent component, choose an available installed agent, or continue recording without AI insights. See AI cleanup and Meeting mode.

Remote host is unreachable#

Confirm that the host is awake, OpenWhisper is running, and engine sharing is enabled. Check the address, pairing status, and host firewall. Both computers need a network path to one another.

When using Tailscale, confirm both computers are connected to the intended tailnet. Return to Remote engines to pair again if access was revoked.

Get help#

Use GitHub Discussions for setup questions or open an issue for a reproducible bug.

Include the app version, operating system and architecture, speech engine and model, what you expected, what happened, and the exact error. Describe whether the problem also occurs with the in-app button or a CPU model. Remove API keys and private transcript content from anything you share.