Skip to main content
This page covers the most common problems and how to fix them. Jump to the symptom that matches what you’re seeing.

​
Recording issues

​
App is not recording / recording won’t start

HyperWhisper needs Microphone permission before it can record anything. Without it, recording fails immediately.
Go to System Settings → Privacy & Security → Microphone and enable HyperWhisper. If you clicked “Don’t Allow” during the initial prompt, the toggle may be off.You can also reset the permission and re-grant it from scratch:
tccutil reset Microphone com.hyperwhisper.hyperwhisper
Then relaunch HyperWhisper and click OK when prompted.
See Permissions for the full grant flow.
If no audio input device is present when you start recording, the recording cannot begin.Common causes:
  • USB microphone was unplugged
  • Bluetooth headset disconnected or went to sleep
  • All input devices disabled in system sound settings
Fix: Reconnect the device, then check that it appears in the microphone list:
Click the HyperWhisper icon in the menu bar, hover over Microphone, and confirm your device appears and is selected. Also check System Settings → Sound → Input to confirm the device is listed.
See Select a Microphone for details on device selection and fallback behavior.
On macOS, two apps cannot always share the same microphone input simultaneously. If another app has an exclusive hold on the microphone, HyperWhisper shows an error when you try to start recording.Fix: Quit competing apps that may be holding the microphone open — common culprits include Zoom, Microsoft Teams, FaceTime, and Voice Memos. Then try recording again.
Push-to-talk using a bare modifier key (Option or Control held alone, without another key) requires Accessibility permission. Standard combinations like ⌥ Space do not require it.macOS does not prompt for Accessibility automatically — you must grant it manually.
1

Open Accessibility settings

Go to System Settings → Privacy & Security → Accessibility.
2

Enable HyperWhisper

Click the lock icon, authenticate, then enable HyperWhisper in the list.
3

Restart HyperWhisper

Quit and reopen the app so the new permission takes effect.
If you are running a development build from Xcode, the entry in the Accessibility list will show the Xcode DerivedData path rather than /Applications/HyperWhisper.app. You may need to enable both entries if you switch between them. The entry must match the path of the currently running build.
See Permissions for more on the Accessibility grant flow.

​
Transcription output issues

​
No output / blank transcript

The transcription provider analyzed the audio but found no recognizable speech. This is a real signal, not a silent failure.Common causes:
  • The recording captured silence (microphone muted, very low input volume)
  • Background noise was louder than your voice
  • You were too far from the microphone
Fix: Check your microphone input level in System Settings → Sound → Input (macOS) or Sound Settings → Recording (Windows), and speak closer to the microphone. See Audio Input Volume and Best Practices for guidance on environment and microphone positioning.
When language is set to Auto-detect, the provider needs enough audio to identify which language you are speaking. For recordings under 10–15 seconds, detection can fail or produce output in the wrong language.Fix: Set an explicit language in your mode settings instead of relying on auto-detect. See Best Practices for why this matters.
When transcribing a file, the provider may reject audio in an unsupported codec.Fix: Convert the file to WAV, MP3, or M4A before importing. See Transcribe a File for supported formats and provider-specific size limits.
If you have selected a local model but it is not downloaded yet — or the download was corrupted — transcription cannot proceed.
Open Model Library, find the model you are using, and check its status. If it shows a Download button, click it. If it appears downloaded but transcription still fails, remove the model and re-download it.

​
Permission & access issues

​
”Accessibility permission required”

Accessibility permission is needed for two features on macOS: auto-paste (pasting the transcript into the frontmost app) and bare-modifier push-to-talk (hold-to-record on a single modifier key).
1

Open Accessibility settings

Go to System Settings → Privacy & Security → Accessibility.
2

Add HyperWhisper

Click the lock icon and authenticate, then enable HyperWhisper in the list. macOS does not auto-prompt for this permission — you must add it manually.
3

Restart HyperWhisper

Quit and reopen the app.
If you use HyperWhisper from Xcode DerivedData alongside the installed /Applications/HyperWhisper.app, you may need two separate entries in the Accessibility list — one for each path. Enable the entry that matches the build you are currently running.
Without Accessibility: auto-paste does nothing (the transcript stays on the clipboard); bare-modifier push-to-talk does not activate. Standard hotkey combinations still work without it. See Permissions for the full permission overview.

​
”Screen Recording permission needed”

Screen Recording permission is only required for Screen OCR mode, which reads on-screen text into your transcript context. No other mode needs it. Grant it at System Settings → Privacy & Security → Screen Recording, then restart HyperWhisper. Without it, Screen OCR mode fails silently while all other modes continue to work normally.

​
Network & cloud provider issues

​
Cloud transcription failing

HyperWhisper cannot reach the cloud provider.Common symptoms: timeout errors, connection refused, DNS failures.Fix: Check your internet connection and retry the transcription. If the problem persists, check the provider’s status page or HyperWhisper’s LinkedIn for outage announcements.
A missing or revoked API key causes 401 or 403 HTTP errors.
Go to Model Library → API Keys and verify the key for the provider you are using.
If the key was recently regenerated on the provider’s dashboard, update it in HyperWhisper’s settings. HyperWhisper Cloud does not require an API key — it uses your license.
Your account has run out of credits or exceeded the provider’s usage quota.For HyperWhisper Cloud: Top up credits from the billing dashboard (accessible via Settings → Credits). See Pricing & Trial Limits for credit rates.For BYOK providers: Log in to the provider’s billing page and add credits or raise your quota limit. See Providers for links.
The provider’s servers returned a 5xx error. This is transient and not caused by your configuration.Fix: Wait a few minutes and retry. If the outage continues, switch to a local model or a different cloud provider. Check HyperWhisper’s LinkedIn for status updates during widespread outages.
You have sent requests faster than the provider allows.When rate limited, HyperWhisper may display the suggested wait duration if the provider includes a Retry-After header.Fix: Wait the indicated duration, then retry. If you hit rate limits consistently, consider upgrading your plan with the provider or switching to a provider with a higher limit. See Providers.

​
Model download issues

​
Download stuck or won’t complete

If your internet connection drops during a model download, the download may stall.Fix: Check your connection and click Cancel in Model Library, then start the download again. If the partially downloaded file appears to be corrupted after multiple attempts, restart the app to clear any in-memory state before retrying.
Models range from about 39–78 MB (Whisper Tiny) to 2.9–3.1 GB (Whisper Large) depending on platform. If your disk is nearly full, the download will fail or stall near completion.Fix: Free up disk space, then retry the download. Alternatively, choose a smaller model — Whisper Small (~466–488 MB depending on platform) gives a good balance of accuracy and size for most users.Models are stored at:
  • macOS: ~/Library/Application Support/hyperwhisper/models/
  • Windows: %LOCALAPPDATA%\HyperWhisper\Models\
Some models are only available on a Pro license or require an active subscription.Fix: Check your license status in Settings → License. If your license has expired or does not include the model tier, renew it or contact support@hyperwhisper.com. See Pricing & Trial Limits.

​
Streaming issues

​
Streaming not working or words not appearing

Streaming is off by default and must be turned on before any streaming shortcut or setting becomes active.
Open the Streaming section in the sidebar and turn on Enable Streaming. The shortcut field and provider options appear once the toggle is on.
The on-device streaming providers (Parakeet and Nemotron 3.5, macOS only) must be downloaded before first use.Fix: In Settings → Streaming → Engine, find the model you want and click Install. Wait for the download to complete before triggering streaming.
Streaming can be interrupted by a network dropout (for cloud providers), a provider timeout, or the audio input being disconnected mid-session.Fix: Check your internet connection and microphone. Restart streaming by pressing your shortcut again. If your microphone disconnected, reconnect it and try again.
Vocabulary boosting during streaming is only supported by HyperWhisper Cloud and Deepgram (when an explicit language is set — not Auto). ElevenLabs, OpenAI, and xAI do not support vocabulary boosting in the streaming API.A warning appears in the streaming settings if you have vocabulary entries and switch to a provider that does not support them.Fix: Switch to HyperWhisper Cloud or Deepgram, and set an explicit language (not Auto) when using Deepgram. See Streaming Transcription.
With Fast Formatting enabled (the default), Deepgram returns results immediately without waiting for additional surrounding context — words appear faster but punctuation and number formatting may be less accurate. With it disabled, Deepgram waits for more context before finalizing, producing slightly more accurate formatting at the cost of extra latency.Fix: Adjust the Fast Formatting toggle in the Streaming section based on whether you prefer lower latency or more accurate formatting.

​
Audio input & device issues

​
Microphone input level too low or too high

If your microphone is too quiet, the transcription provider receives audio that is too faint to transcribe reliably. If it is too loud, it may clip. Fix: Adjust the system input volume:
Go to System Settings → Sound → Input, select your device, and raise the Input volume slider until speech at your normal dictation level moves the Input level meter to around the middle.
HyperWhisper also has an Auto-Increase Microphone Volume option in Settings → Sound that temporarily boosts the input level to 90% at the start of each recording. See Audio Input Volume.

​
Keep Microphone Warm not behaving as expected

Keep Microphone Warm holds an idle capture stream open between recordings to reduce push-to-talk startup delay. It is particularly useful for Bluetooth devices that power down their microphone when idle. Note that it does not guarantee zero startup delay — Bluetooth devices may still apply their own power-saving logic despite the stream being open. If this remains a problem, a USB microphone provides more consistent startup latency. Enable or disable it in Settings → Sound → Keep Microphone Warm.
While Keep Microphone Warm is on, macOS shows the orange microphone indicator in the menu bar continuously and Bluetooth headsets may remain in their lower-quality call audio profile rather than switching to stereo. Turn it off if those trade-offs matter to you.

​
Wrong audio input device selected

Click the HyperWhisper icon in the menu bar, hover over Microphone, and select the correct device. A checkmark appears next to the active device.

​
Audio device disconnected mid-recording

If your selected device disconnects during recording, HyperWhisper clears the selection and falls back to the macOS system default input device. The recording in progress may fail.
Reconnect the device and verify the selection in the Microphone menu before recording again. See Select a Microphone.

​
When to contact support

If none of the above resolves your issue, reach out at support@hyperwhisper.com. To speed up diagnosis, include:
  • Your operating system and version
  • HyperWhisper version (visible in Settings → General on macOS, or Settings → About on Windows)
  • Whether you are using a local model, HyperWhisper Cloud, or a BYOK provider
  • A description of what happened and what you expected
Attaching the app log makes diagnosis significantly faster:
Use the Debug menu in the app’s menu bar and select Export Logs. Attach the exported log file.
See Support & Refunds for more detail on what to include and typical response times.