Skip to main content
This page lists the most common problems and their fixes. Go to the symptom that matches your problem.

​
Recording issues

​
App does not record or recording does not start

HyperWhisper must have Microphone permission to record. Without this permission, the recording fails immediately.
Go to System Settings → Privacy & Security → Microphone. Then enable HyperWhisper. If you clicked “Don’t Allow” at the first prompt, the toggle is off.You can also reset the permission and grant it again:
Then start HyperWhisper again. Click OK at the prompt.
For the full grant procedure, see Permissions.
If no audio input device is available when you start, the recording cannot start.On macOS, HyperWhisper does not fail immediately. It looks for an input device up to 7 times, across approximately 3.2 seconds, before it shows this error. This delay exists because macOS can report zero input devices for a short time during an audio route change — a Bluetooth disconnect, a USB audio device that you remove, AirPods that connect again, or a wake from sleep. A Mac that has a real microphone usually recovers inside this window and the recording starts as normal. A machine with no input device at all answers immediately, so it does not wait.The usual causes are:
  • The USB microphone is disconnected
  • The Bluetooth headset is disconnected or in sleep mode
  • All input devices are disabled in the system sound settings
Fix: Connect the device again. Then make sure that it is in the microphone list:
Click the HyperWhisper icon in the menu bar. Move the pointer over Microphone. Make sure that your device is in the list and selected. Then open System Settings → Sound → Input. Make sure that the device is in this list.
For more about device selection and fallback behavior, see Select a Microphone.
On macOS, two apps cannot always use the same microphone input at the same time. If another app holds the microphone, HyperWhisper shows an error when you start a recording.Fix: Quit the other apps that hold the microphone open. The usual apps are Zoom, Microsoft Teams, FaceTime, and Voice Memos. Then start the recording again.
Push-to-talk with a bare modifier key needs Accessibility permission. A bare modifier key is Option or Control held alone, without another key. Standard combinations such as ⌥ Space do not need this permission.macOS does not prompt for Accessibility. You must grant this permission manually.
1

Open Accessibility settings

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

Enable HyperWhisper

Click the lock icon and authenticate. Then enable HyperWhisper in the list.
3

Go back to HyperWhisper

The new permission takes effect while the app runs. You do not need to start the app again — HyperWhisper watches for the grant and arms push-to-talk as soon as it finds it. The app watches for 10 minutes. If you take longer, select the push-to-talk mode again in Settings → Shortcuts, or start the app again.
For a development build from Xcode, the entry in the Accessibility list shows the Xcode DerivedData path, not /Applications/HyperWhisper.app. If you change between the two builds, both entries must be enabled. The enabled entry must match the path of the build that runs now.
For more about the Accessibility grant procedure, see Permissions.

​
Transcription output issues

​
No output or blank transcript

The transcription provider analyzed the audio and found no speech. Usually this result is correct, and not a hidden failure.The app does a check on the result. After each No speech detected, the app measures the audio. If the measurement shows speech, the engine and the recording disagree, and the app sends one report to the crash reporter. This report holds measurements only, and no audio and no text. It goes only if you turn on Error logging (macOS) or Send error reports (Windows). Read Data Privacy for the full list.The usual causes are:
  • The recording contains only silence (muted microphone, very low input volume)
  • The background noise was louder than your voice
  • You were too far from the microphone
Fix: Look at your microphone input level in System Settings → Sound → Input (macOS) or Sound Settings → Recording (Windows). Then speak closer to the microphone. For more about your environment and the microphone position, see Audio Input Volume and Best Practices.
When the language is Auto-detect, the provider needs sufficient audio to identify your language. For recordings shorter than 10–15 seconds, the detection can fail or give the wrong language.Fix: Set an explicit language in your mode settings. Do not use auto-detect. For the reason, see Best Practices.
The provider can reject a file with an unsupported audio codec.Fix: Convert the file to WAV, MP3, or M4A before you import it. For the supported formats and the size limit of each provider, see Transcribe a File.
If you select a local model that is not downloaded, the transcription cannot start. A corrupted download has the same result.
Open Model Library and find the model that you use. Look at its status. If the model shows a Download button, click the button. If the model is downloaded and the transcription still fails, remove the model and download it again.
HyperWhisper releases the local speech model from memory when macOS has insufficient memory. If this occurs while a transcription runs, the transcription stops with this message:
The speech model was unloaded to free memory and couldn’t be reloaded. Close some apps and try again.
For a Whisper model, HyperWhisper first tries to load the model again, and shows the message only if that load also fails. For a Parakeet model, it shows the message immediately.HyperWhisper does not retry the transcription automatically. The memory pressure is continuous, so more attempts would only load and lose the model again.Fix: Close applications that use much memory. Then make the recording again. If the message occurs frequently, select a smaller local model, or select a cloud provider for the mode.
A Local API client gets the same condition as the ENGINE_UNAVAILABLE error code.

​
Permission & access issues

​
”Accessibility permission required”

Two macOS features need Accessibility permission: auto-paste and bare-modifier push-to-talk. Auto-paste puts the transcript into the frontmost app. Bare-modifier push-to-talk records while you hold one 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 prompt for this permission. You must add it manually.
3

Go back to HyperWhisper

The new permission takes effect while the app runs. Auto-paste examines the permission at each use, and bare-modifier push-to-talk starts as soon as the app finds the grant. Start the app again only if you granted the permission more than 10 minutes after the app found it missing.
If you use HyperWhisper from Xcode DerivedData and the installed /Applications/HyperWhisper.app, the Accessibility list needs two entries, one for each path. The enabled entry must match the build that runs now.
Without Accessibility: auto-paste does nothing, and the transcript stays on the clipboard. Bare-modifier push-to-talk does not start. Standard hotkey combinations continue to work. For the full permission overview, see Permissions.

​
”Screen Recording permission needed”

Only Screen OCR mode needs Screen Recording permission. This mode reads on-screen text into your transcript context. No other mode needs this permission. Grant the permission at System Settings → Privacy & Security → Screen Recording. Then quit HyperWhisper and open it again. Without this permission, Screen OCR mode fails without a message. All other modes continue to work.

​
Network & cloud provider issues

​
Cloud transcription fails

HyperWhisper cannot reach the cloud provider.The usual symptoms are timeout errors, connection refused, and DNS errors.Fix: Make sure that your internet connection works. Then start the transcription again. If the error continues, look at the status page of the provider or at HyperWhisper’s LinkedIn for outage announcements.
A missing or revoked API key causes 401 or 403 HTTP errors.
Go to Model Library → API Keys. Make sure that the key for your provider is correct.
If you generated a new key on the dashboard of the provider, put that key in the HyperWhisper settings. HyperWhisper Cloud does not need a provider API key. It uses your HyperWhisper Cloud account key and your credit balance.
Your mode uses HyperWhisper Cloud, but the app has no account key. HyperWhisper Cloud needs an account key for every request. There is no trial and no anonymous use.HyperWhisper stops this transcription on your machine, before the upload. Your audio does not go to the server. The error shows immediately, and it names HyperWhisper Cloud.Fix: Open Settings → HyperWhisper Cloud. Then enter your account key, or click Get Credits to buy credits and create a key. Read Pricing & Cloud Credits for the steps. To transcribe without a Cloud account, change the mode to a local model, or to a provider for which you hold your own API key.
Your account has no more credits, or your use is more than the quota of the provider.For HyperWhisper Cloud: Add credits from the billing dashboard. To open the dashboard, go to Settings → HyperWhisper Cloud. For the credit rates, see Pricing & Cloud Credits.For BYOK providers: Log in to the billing page of the provider. Then add credits or increase your quota limit. For the links, see Providers.
The servers of the provider returned a 5xx error. This error is temporary. Your settings did not cause it.Fix: Wait a few minutes. Then try again. If the outage continues, change to a local model or to a different cloud provider. During a large outage, look at HyperWhisper’s LinkedIn for status updates.
You sent requests faster than the provider permits.If the provider includes a Retry-After header, HyperWhisper shows the suggested wait duration.Fix: Wait for that duration. Then try again. If the rate limit occurs frequently, upgrade your plan with the provider. You can also change to a provider with a higher limit. See Providers.

​
Model download issues

​
Download stops or does not complete

If your internet connection stops during a model download, the download can stop before it is complete.Fix: Make sure that your connection works. Then click Cancel in Model Library and start the download again. If the incomplete file is still corrupted after more attempts, quit the app and open it again. This action clears the state in memory. Then start the download again.
The models are from about 39–78 MB (Whisper Tiny) to 2.9–3.1 GB (Whisper Large). The size changes with the platform. If your disk is almost full, the download fails or stops near the end.Fix: Make more disk space available. Then start the download again. You can also select a smaller model. For most users, Whisper Small gives a good balance of accuracy and size. Its size is 466–488 MB and changes with the platform.HyperWhisper stores the models at:
  • macOS: ~/Library/Application Support/hyperwhisper/models/
  • Windows: %LOCALAPPDATA%\HyperWhisper\Models\

​
Streaming issues

​
Streaming does not work or words do not appear

Streaming is off by default. You must enable it before a streaming shortcut or setting becomes active.
Open the Streaming section in the sidebar. Then enable the Enable Streaming toggle. The shortcut field and the provider options appear when the toggle is on.
You must download the on-device streaming providers before the first use. These providers are Parakeet and Nemotron 3.5, on macOS only.Fix: In Settings → Streaming → Engine, find the model and click Install. Wait until the download is complete. Then start streaming.
Three conditions can interrupt streaming: a network dropout with a cloud provider, a provider timeout, or an audio input that disconnects during the session.Fix: Make sure that your internet connection and your microphone work. Then press your shortcut again to start streaming. If the microphone is disconnected, connect it again.
Only HyperWhisper Cloud, Deepgram and xAI support vocabulary boosting during streaming. HyperWhisper Cloud and Deepgram support it only with an explicit language, not Auto. xAI accepts the terms with any language. ElevenLabs and OpenAI do not support vocabulary boosting in the streaming API.If you have vocabulary entries and change to a provider without this support, the streaming settings show a warning.Fix: Change to HyperWhisper Cloud, Deepgram or xAI. For HyperWhisper Cloud and Deepgram, also set an explicit language, not Auto. See Streaming Transcription.
Fast Formatting is on by default. With this option on, Deepgram returns each result immediately and does not wait for more context. The words appear faster, but the punctuation and the number formatting can be less accurate. With this option off, Deepgram waits for more context before it makes a result final. The formatting is a little more accurate, but the latency is higher.Fix: Set the Fast Formatting toggle in the Streaming section. For lower latency, turn it on. For more accurate formatting, turn it off.

​
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 for a reliable transcription. If your microphone is too loud, the audio can clip. Fix: Set the system input volume:
Go to System Settings → Sound → Input and select your device. Then speak at your usual dictation level. Increase the Input volume slider until the Input level meter moves to about the middle.
HyperWhisper also has an Auto-Increase Microphone Volume option in Settings → Sound. This option increases the input level to 90% at the start of each recording. The change is temporary. See Audio Input Volume.

​
Keep Microphone Warm has unexpected behavior

Keep Microphone Warm holds an idle capture stream open between recordings. This stream decreases the push-to-talk startup delay. The option helps most with Bluetooth devices that turn off the microphone when idle. The option does not remove all startup delay. A Bluetooth device can apply its own power-saving logic while the stream is open. If the delay continues, a USB microphone gives a more consistent startup latency. Enable or disable this option in Settings → Sound → Keep Microphone Warm.
While Keep Microphone Warm is on, macOS shows the orange microphone indicator in the menu bar continuously. A Bluetooth headset can stay in its lower-quality call audio profile and not change to stereo. If these results are not acceptable to you, you can disable the option.

​
Wrong audio input device selected

Click the HyperWhisper icon in the menu bar. Move the pointer over Microphone. Then select the correct device. A checkmark shows the active device.

​
Audio device disconnected mid-recording

If your selected device disconnects during a recording, HyperWhisper clears the selection. HyperWhisper then uses the macOS default input device. The active recording can fail.
Connect the device again. Then make sure that the selection in the Microphone menu is correct before you record again. See Select a Microphone.

​
When to contact support

If these fixes do not correct your problem, send an email to hi@support.hyperwhisper.com. For a faster diagnosis, include this information:
  • Your operating system and its version
  • The HyperWhisper version, in Settings → General on macOS, or Settings → About on Windows
  • Your provider: a local model, HyperWhisper Cloud, or a BYOK provider
  • A description of the result and of the result that you expected
The app log makes the diagnosis much faster:
Open the Debug menu in the menu bar of the app. Select Export Update Logs…. For a more complete bundle, select Export Diagnostics…. Then attach the exported log file.
For more about the information to include and the usual response times, see Support & Refunds.