Skip to content

Reference

Troubleshooting

Resolve microphone, permission, model, startup, and connection problems.

On this page

Start with a short recording using the in-app button before testing shortcuts, auto-paste, or AI features. That tells you which part of the chain needs attention.

The app will not open#

Confirm the installer matches your platform and architecture. Native macOS packages need Apple Silicon and macOS 14+; Intel Macs run from source.

Verify the download and follow the first-launch steps in Installation. If a packaged app shows an import error, update to the current release rather than adding Python packages to it.

On Linux, if startup used to hang on "Creating interface…", update: OpenWhisper now gives up on a keyring that doesn't answer and opens without saved keys. Settings → App → API keys explains what it found.

The app asks to restart after an update#

When a package upgrade or git pull replaces OpenWhisper while it's running, it offers Restart now as soon as nothing is recording or transcribing. Accept it: features loaded after the update would otherwise mix old and new code and fail with errors such as “cannot import name.”

The microphone is silent#

Check Settings → Dictation → Recording and select the intended microphone. Confirm it works in another app and that your operating system lets OpenWhisper use it. On macOS, allow Microphone in System Settings → Privacy & Security, then try Quick Record's button again.

A model or runtime is missing#

Open Settings → Models & storage → Downloads and check the selected model's required components. Optional engines need both model weights and a runtime. Download errors say what went wrong, such as no connection or not enough disk space.

If you're offline, reconnect to install it or pick a model already downloaded. If installation is blocked, check When a model is missing from this computer on the same page.

GPU acceleration is unavailable#

Check the engine's platform support in Choosing a model. Local Whisper on macOS uses the CPU; its NVIDIA GPU Acceleration component is for Windows and Linux. Parakeet and Nemotron need NVIDIA Speech GPU (or the Vulkan version for older cards on Linux), Parakeet Unified uses the transcribe.cpp runtime with any vendor's GPU through Vulkan, and Qwen3-ASR has its own runtime in Components.

Switch the device to CPU to confirm transcription works while you investigate a GPU problem.

Hotkeys or auto-paste do not work#

Confirm your shortcuts in Settings → App → Hotkeys, using keys your keyboard actually has, and check for conflicts with other apps.

On macOS, auto-paste needs Accessibility permission: Settings → App → General → Set up auto-paste… names the app to allow. After an update, OpenWhisper reopens that window on launch; use Open Accessibility Settings there and turn the current app on. If the switch is already on but access isn't detected, choose Repair old Accessibility entry…, which removes only OpenWhisper's entry, then turn it on again. If repair fails, the window explains how to remove and re-add the entry by hand. If access still isn't detected, quit and reopen OpenWhisper. Global hotkeys don't need Accessibility.

On Linux, X11 supports global hotkeys and auto-paste. Omarchy has desktop integration; other Wayland desktops use focused-window shortcuts and manual paste. If a shortcut is pressed while a transcription is still running, a notice next to the pointer says so instead of starting a new recording.

Walkthrough screenshots fail#

On macOS, the first snap asks for Screen & System Audio Recording. Allow OpenWhisper in System Settings → Privacy & Security, then reopen it. If the switch is already on, fully quit OpenWhisper and launch it again. If it still fails after an update, remove OpenWhisper from the list with −, add /Applications/OpenWhisper.app again with +, turn it on, and reopen the app. On Hyprland, install grim. Other Wayland desktops aren't supported yet.

If an AI write-up fails, the walkthrough is still copied as spoken and the status says why. Usually the chosen agent isn't installed or signed in; Settings → Dictation → Walkthroughs marks agents it can't find. Retry AI write-up in Saved Walkthroughs (open it from the Walkthroughs side panel) tries again without re-recording. See Walkthroughs.

Meeting system audio is missing#

On macOS, allow Screen & System Audio Recording. Open Meeting setup… in Meeting Mode, choose Check microphone and system audio, and play something through the output your calls use.

Linux needs PulseAudio or PipeWire-Pulse and a working monitor for the default output. Use the readiness dialog's Retry detection, then the Linux audio diagnostics. Linux meeting capture is still a preview.

AI cleanup, insights, or actions fail#

Check the provider, address, model, API key, and network connection. Custom endpoints must use the API your server speaks: Chat Completions or Responses. For a local server, make sure it's running; the model picker marks running servers. For a coding agent, confirm it's installed and signed in, then use Look again on the AI cleanup page.

Cleanup failures keep the raw transcript, and failed actions copy your words so nothing is lost. For meetings, pick an available engine or keep recording without AI insights. See AI cleanup, Meeting mode, and Actions & automation.

Remote host is unreachable#

If the host drops while you dictate, the recording overlay shows up to three reconnect attempts within 12 seconds. If they fail, the recording is kept in History with Retry transcription.

Confirm the host is awake, OpenWhisper is running, and sharing is on. In Settings → Dictation → Remote engine → Use another computer, refresh discovery; if the host is missing, try Check every address or Enter an address. On the host, check Share this computer for firewall or network warnings. Both computers need a network path to each other.

With Tailscale, confirm both computers are on the intended tailnet. On macOS, if pairing stopped at saving the key, use Retry Keychain access. If access was revoked, pair again from Remote engines.

Update checks fail#

A certificate error usually means security software is inspecting HTTPS traffic. Ask IT to allow api.github.com, github.com, and release-assets.githubusercontent.com. When GitHub's API is rate-limited, OpenWhisper falls back to the regular release page on its own.

Get help#

Ask setup questions in GitHub Discussions 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. Say whether it also happens with the in-app button or a CPU model. Launching OpenWhisper with --diagnostics writes a local report file you can attach; nothing is uploaded. Remove API keys and private transcript content from anything you share.

Checked against OpenWhisper 2.8.97.App documentation
Still stuck?

Get help from the community, or tell us what went wrong.