Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.
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
Microphone permission not granted
HyperWhisper must have Microphone permission to record. Without this permission, the recording fails immediately.
macOS
Windows
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:
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:
macOS
Windows
Open Settings → Sound and look at the Microphone picker. You can also click the HyperWhisper icon in the menu bar and 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.
In HyperWhisper, open Settings → Sound and select your device in the Microphone picker. You can also right-click the HyperWhisper tray icon and move the pointer over Microphone. Then open Windows Settings → System → Sound. Make sure that the device is enabled.
For more about device selection and fallback behavior, see Select a Microphone.
Microphone is in use by another app
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.
Bare-modifier push-to-talk not working (macOS)
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 → Keyboard 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
No speech detected in the recording
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.
Wrong language — auto-detect on short recordings
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.
Audio format not supported (file transcription)
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.
Local model not downloaded or unavailable
If you select a local model that is not downloaded, the transcription cannot start. A corrupted download has the same result.
macOS
Windows
The alert names the mode and the model, for example: “<Mode> uses <Model>, which is not downloaded. Download it in Model Library.” If this occurs when you transcribe a file, the alert also has an Open Model Library button.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.
Open Model Library and find the model in your settings. If the status shows that the model is missing, download it again. If the Parakeet daemon crashes or times out again and again, quit the app and open it again. A crash during a transcription can leave the daemon in an incorrect state.If you see “Windows Application Control blocked <file>, a file HyperWhisper needs. Ask your IT administrator to allow HyperWhisper, or check Smart App Control in Windows Security.”, a Windows policy stopped a HyperWhisper file from loading, for example the Parakeet daemon. Ask your IT administrator to allow HyperWhisper, or check Smart App Control in Windows Security.
The speech model was unloaded to free memory (macOS)
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
Network connectivity lost
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.
API key missing or invalid
A missing or revoked API key causes 401 or 403 HTTP errors.
macOS
Windows
Go to Model Library → API Keys. Make sure that the key for your provider is correct.
Go to Model Library → API Keys. Make sure that the key 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.
HyperWhisper Cloud requires an account key
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.
HyperWhisper Cloud rejects a request with 401 or 403
These status codes have different meanings for HyperWhisper Cloud:
401 — the account key is invalid or expired. Open Settings → HyperWhisper Cloud and update the key.
403 — HyperWhisper Cloud temporarily blocked the network. Wait a few minutes, then try again. Changing the account key does not correct this network block.
Insufficient credits or quota exceeded
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.Some providers report an empty account with an authentication status code. HyperWhisper shows these as this quota error, not as an invalid API key: an ElevenLabs 401 response with quota_exceeded, and a SpaceXAI 403 response that says the account used all available credits.
Provider temporarily unavailable (server errors)
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.
Rate limited (429 errors)
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
Network connection interrupted
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.
Insufficient disk space
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.On Windows, HyperWhisper checks the free space before a Whisper or local LLM download starts. It needs the size of the model plus 10%. If there is not enough space, the download does not start, and you see “Not enough disk space to download” with the model name, the space needed, and the space available.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:
Streaming is off by default. You must enable it before a streaming shortcut or setting becomes active.
macOS
Windows
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.
Click Streaming in the main sidebar. Then select the Enable Streaming checkbox.
On-device streaming model not downloaded
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.
Streaming interrupted or cut off mid-sentence
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.
Vocabulary not boosting in streaming
Only HyperWhisper Cloud, Deepgram and SpaceXAI support vocabulary boosting during streaming. HyperWhisper Cloud and Deepgram support it only with an explicit language, not Auto. SpaceXAI 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 SpaceXAI. For HyperWhisper Cloud and Deepgram, also set an explicit language, not Auto. See Streaming Transcription.
Deepgram Fast Formatting not behaving as expected
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:
macOS
Windows
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.
Right-click the speaker icon in the taskbar → Open Sound settings → Sound Control Panel → Recording. Double-click your microphone. Then open the Levels tab and increase the slider.
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
macOS
Windows
Open Settings → Sound and select the correct device in the Microphone picker. You can also click the HyperWhisper icon in the menu bar, move the pointer over Microphone, and select the device. A checkmark shows the active device.
Open Settings → Sound and select the correct device in the Microphone picker. You can also right-click the HyperWhisper tray icon, move the pointer over Microphone, and select the device.
Audio device disconnected mid-recording
macOS
Windows
If your selected device disconnects during a recording, HyperWhisper keeps your choice. The recording continues on the macOS default input device, in the same file. Later recordings use your device again when it is reconnected.
If you remove the selected device, HyperWhisper keeps your choice and uses the Windows default input device until the device is reconnected. When the device returns, HyperWhisper matches it by name and changes back to it.
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:
macOS
Windows
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.If HyperWhisper cannot read its system logs, Export Diagnostics… still saves the file. The alert “Diagnostics Exported Without System Logs” appears, and system-logs.txt in the file holds only the reason.
Press Win + R. Paste %LOCALAPPDATA%\HyperWhisper\Logs and press Enter. Then attach the most recent hyperwhisper-YYYY-MM-DD.log file.
For more about the information to include and the usual response times, see Support & Refunds.
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"HyperWhisper","description":"AI-powered speech-to-text transcription for macOS, Windows, and Linux","colors":{"primary":"#9810FA","light":"#C27AFF","dark":"#6E11B0"},"logo":{"light":"https://mintcdn.com/rayamjadltd/pEagBiOtc1Gduti1/assets/logo.png?fit=max\u0026auto=format\u0026n=pEagBiOtc1Gduti1\u0026q=85\u0026s=febbecb9bbdcca3ff60d262dd6f781d0","dark":"https://mintcdn.com/rayamjadltd/hyEmpq5i1TrK7gUr/assets/logo-dark.png?fit=max\u0026auto=format\u0026n=hyEmpq5i1TrK7gUr\u0026q=85\u0026s=4cae486ec2329ca69580f41a1f870615"},"favicon":"https://mintcdn.com/rayamjadltd/pEagBiOtc1Gduti1/assets/favicon.png?fit=max\u0026auto=format\u0026n=pEagBiOtc1Gduti1\u0026q=85\u0026s=a0543755c479b1b2fde3874bfdccc88e","appearance":{"default":"dark"},"navbar":{"primary":{"type":"button","label":"Get HyperWhisper","href":"https://www.hyperwhisper.com"}},"footer":{"socials":{"linkedin":"https://www.linkedin.com/company/hyperwhisper"},"links":[{"header":"Product","items":[{"label":"Website","href":"https://www.hyperwhisper.com"},{"label":"Download","href":"https://www.hyperwhisper.com"}]},{"header":"Support","items":[{"label":"Email Support","href":"https://hyperwhisper.com/support"},{"label":"Documentation","href":"https://hyperwhisper.com/docs"}]}]},"contextual":{"options":["copy","view","chatgpt","claude","perplexity"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"rayamjadltd","hasAudioNarration":false,"actualSubdomain":"rayamjadltd","customDomains":["hyperwhisper.com"],"gitSource":{"type":"github","owner":"ray-amjad","repo":"hyperwhisper-app","deployBranch":"main","contentDirectory":"mintlify-help","isPrivate":false,"mountPath":"","label":""},"feedback":{"thumbs":true},"entitlements":{},"buildId":"6ae497a6d9167d81040eac80","clientVersion":"0.0.4167","searchFilterCounts":[{"language":"default","tag":"Developer \u0026 API","count":18},{"language":"default","tag":"Local API Reference","count":16},{"language":"default","tag":"Features","count":16},{"language":"default","tag":"API Reference","count":14},{"language":"default","tag":"Settings","count":6},{"language":"default","tag":"Transcription \u0026 Models","count":6},{"language":"default","tag":"Getting Started","count":6},{"language":"default","tag":"Troubleshooting","count":6},{"language":"default","tag":"Audio Input","count":5},{"language":"default","tag":"Plans \u0026 Billing","count":3}]},"assistantConfig":{},"basePath":"/docs","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"troubleshooting","slug":"/troubleshooting","pageMetadata":{"title":"Troubleshooting","description":"Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.","href":"/troubleshooting"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,blockquote:`blockquote`,code:`code`,hr:`hr`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{Accordion,AccordionGroup,CodeBlock,Heading,Note,Step,Steps,Tab,Tabs}=_components;if(!Accordion)_missingMdxReference(`Accordion`,true);if(!AccordionGroup)_missingMdxReference(`AccordionGroup`,true);if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);if(!Step)_missingMdxReference(`Step`,true);if(!Steps)_missingMdxReference(`Steps`,true);if(!Tab)_missingMdxReference(`Tab`,true);if(!Tabs)_missingMdxReference(`Tabs`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`This page lists the most common problems and their fixes. Go to the symptom that matches your problem.`}),`\n`,_jsx(Heading,{level:`2`,id:`recording-issues`,children:`Recording issues`}),`\n`,_jsx(Heading,{level:`3`,id:`app-does-not-record-or-recording-does-not-start`,children:`App does not record or recording does not start`}),`\n`,_jsxs(AccordionGroup,{children:[_jsxs(Accordion,{title:`Microphone permission not granted`,id:`microphone-permission-not-granted`,children:[_jsx(_components.p,{children:`HyperWhisper must have Microphone permission to record. Without this permission, the recording fails immediately.`}),_jsxs(Tabs,{children:[_jsxs(Tab,{title:`macOS`,id:`macos`,children:[_jsxs(_components.p,{children:[`Go to `,_jsx(_components.strong,{children:`System Settings → Privacy \u0026 Security → Microphone`}),`. Then enable `,_jsx(_components.strong,{children:`HyperWhisper`}),`. If you clicked “Don’t Allow” at the first prompt, the toggle is off.`]}),_jsx(_components.p,{children:`You can also reset the permission and grant it again:`}),_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`tccutil`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` reset`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Microphone`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` com.hyperwhisper.hyperwhisper`})]}),`\n`]})})}),_jsxs(_components.p,{children:[`Then start HyperWhisper again. Click `,_jsx(_components.strong,{children:`OK`}),` at the prompt.`]})]}),_jsx(Tab,{title:`Windows`,id:`windows`,children:_jsxs(_components.p,{children:[`Go to `,_jsx(_components.strong,{children:`Settings → Privacy \u0026 Security → Microphone`}),`. Make sure that microphone access is enabled for desktop apps.`]})})]}),_jsxs(_components.p,{children:[`For the full grant procedure, see `,_jsx(_components.a,{href:`/permissions`,children:`Permissions`}),`.`]})]}),_jsxs(Accordion,{title:`No microphone available / device disconnected`,id:`no-microphone-available-device-disconnected`,children:[_jsx(_components.p,{children:`If no audio input device is available when you start, the recording cannot start.`}),_jsx(_components.p,{children:`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.`}),_jsx(_components.p,{children:`The usual causes are:`}),_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`The USB microphone is disconnected`}),`\n`,_jsx(_components.li,{children:`The Bluetooth headset is disconnected or in sleep mode`}),`\n`,_jsx(_components.li,{children:`All input devices are disabled in the system sound settings`}),`\n`]}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` Connect the device again. Then make sure that it is in the microphone list:`]}),_jsxs(Tabs,{children:[_jsx(Tab,{title:`macOS`,id:`macos-2`,children:_jsxs(_components.p,{children:[`Open `,_jsx(_components.strong,{children:`Settings → Sound`}),` and look at the `,_jsx(_components.strong,{children:`Microphone`}),` picker. You can also click the HyperWhisper icon in the menu bar and move the pointer over `,_jsx(_components.strong,{children:`Microphone`}),`. Make sure that your device is in the list and selected. Then open `,_jsx(_components.strong,{children:`System Settings → Sound → Input`}),`. Make sure that the device is in this list.`]})}),_jsx(Tab,{title:`Windows`,id:`windows-2`,children:_jsxs(_components.p,{children:[`In HyperWhisper, open `,_jsx(_components.strong,{children:`Settings → Sound`}),` and select your device in the `,_jsx(_components.strong,{children:`Microphone`}),` picker. You can also right-click the HyperWhisper tray icon and move the pointer over `,_jsx(_components.strong,{children:`Microphone`}),`. Then open Windows `,_jsx(_components.strong,{children:`Settings → System → Sound`}),`. Make sure that the device is enabled.`]})})]}),_jsxs(_components.p,{children:[`For more about device selection and fallback behavior, see `,_jsx(_components.a,{href:`/microphone-selection`,children:`Select a Microphone`}),`.`]})]}),_jsxs(Accordion,{title:`Microphone is in use by another app`,id:`microphone-is-in-use-by-another-app`,children:[_jsx(_components.p,{children:`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.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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.`]})]}),_jsxs(Accordion,{title:`Bare-modifier push-to-talk not working (macOS)`,id:`bare-modifier-push-to-talk-not-working-macos`,children:[_jsxs(_components.p,{children:[`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 `,_jsx(_components.strong,{children:`⌥ Space`}),` do not need this permission.`]}),_jsx(_components.p,{children:`macOS does not prompt for Accessibility. You must grant this permission manually.`}),_jsxs(Steps,{children:[_jsx(Step,{title:`Open Accessibility settings`,children:_jsxs(_components.p,{children:[`Go to `,_jsx(_components.strong,{children:`System Settings → Privacy \u0026 Security → Accessibility`}),`.`]})}),_jsx(Step,{title:`Enable HyperWhisper`,children:_jsxs(_components.p,{children:[`Click the lock icon and authenticate. Then enable `,_jsx(_components.strong,{children:`HyperWhisper`}),` in the list.`]})}),_jsx(Step,{title:`Go back to HyperWhisper`,children:_jsxs(_components.p,{children:[`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 `,_jsx(_components.strong,{children:`Settings → Keyboard Shortcuts`}),`, or start the app again.`]})})]}),_jsx(Note,{children:_jsxs(_components.p,{children:[`For a development build from Xcode, the entry in the Accessibility list shows the Xcode DerivedData path, not `,_jsx(_components.code,{children:`/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.`]})}),_jsxs(_components.p,{children:[`For more about the Accessibility grant procedure, see `,_jsx(_components.a,{href:`/permissions`,children:`Permissions`}),`.`]})]})]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`transcription-output-issues`,children:`Transcription output issues`}),`\n`,_jsx(Heading,{level:`3`,id:`no-output-or-blank-transcript`,children:`No output or blank transcript`}),`\n`,_jsxs(AccordionGroup,{children:[_jsxs(Accordion,{title:`No speech detected in the recording`,id:`no-speech-detected-in-the-recording`,children:[_jsx(_components.p,{children:`The transcription provider analyzed the audio and found no speech. Usually this result is correct, and not a hidden failure.`}),_jsxs(_components.p,{children:[`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 `,_jsx(_components.strong,{children:`Error logging`}),` (macOS) or `,_jsx(_components.strong,{children:`Send error reports`}),` (Windows). Read `,_jsx(_components.a,{href:`/data-privacy#the-no-speech-diagnostic`,children:`Data Privacy`}),` for the full list.`]}),_jsx(_components.p,{children:`The usual causes are:`}),_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`The recording contains only silence (muted microphone, very low input volume)`}),`\n`,_jsx(_components.li,{children:`The background noise was louder than your voice`}),`\n`,_jsx(_components.li,{children:`You were too far from the microphone`}),`\n`]}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` Look at your microphone input level in `,_jsx(_components.strong,{children:`System Settings → Sound → Input`}),` (macOS) or `,_jsx(_components.strong,{children:`Sound Settings → Recording`}),` (Windows). Then speak closer to the microphone. For more about your environment and the microphone position, see `,_jsx(_components.a,{href:`/audio-input`,children:`Audio Input Volume`}),` and `,_jsx(_components.a,{href:`/best-practices`,children:`Best Practices`}),`.`]})]}),_jsxs(Accordion,{title:`Wrong language — auto-detect on short recordings`,id:`wrong-language-auto-detect-on-short-recordings`,children:[_jsx(_components.p,{children:`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.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` Set an explicit language in your mode settings. Do not use auto-detect. For the reason, see `,_jsx(_components.a,{href:`/best-practices`,children:`Best Practices`}),`.`]})]}),_jsxs(Accordion,{title:`Audio format not supported (file transcription)`,id:`audio-format-not-supported-file-transcription`,children:[_jsx(_components.p,{children:`The provider can reject a file with an unsupported audio codec.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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 `,_jsx(_components.a,{href:`/file-transcription`,children:`Transcribe a File`}),`.`]})]}),_jsxs(Accordion,{title:`Local model not downloaded or unavailable`,id:`local-model-not-downloaded-or-unavailable`,children:[_jsx(_components.p,{children:`If you select a local model that is not downloaded, the transcription cannot start. A corrupted download has the same result.`}),_jsxs(Tabs,{children:[_jsxs(Tab,{title:`macOS`,id:`macos-3`,children:[_jsxs(_components.p,{children:[`The alert names the mode and the model, for example: “\u003cMode> uses \u003cModel>, which is not downloaded. Download it in Model Library.” If this occurs when you transcribe a file, the alert also has an `,_jsx(_components.strong,{children:`Open Model Library`}),` button.`]}),_jsxs(_components.p,{children:[`Open `,_jsx(_components.strong,{children:`Model Library`}),` and find the model that you use. Look at its status. If the model shows a `,_jsx(_components.strong,{children:`Download`}),` button, click the button. If the model is downloaded and the transcription still fails, remove the model and download it again.`]})]}),_jsxs(Tab,{title:`Windows`,id:`windows-3`,children:[_jsxs(_components.p,{children:[`Open `,_jsx(_components.strong,{children:`Model Library`}),` and find the model in your settings. If the status shows that the model is missing, download it again. If the Parakeet daemon crashes or times out again and again, quit the app and open it again. A crash during a transcription can leave the daemon in an incorrect state.`]}),_jsxs(_components.p,{children:[`If you see “Windows Application Control blocked \u003cfile>, a file HyperWhisper needs. Ask your IT administrator to allow HyperWhisper, or check Smart App Control in Windows Security.”, a Windows policy stopped a HyperWhisper file from loading, for example the Parakeet daemon. Ask your IT administrator to allow HyperWhisper, or check `,_jsx(_components.strong,{children:`Smart App Control`}),` in `,_jsx(_components.strong,{children:`Windows Security`}),`.`]})]})]})]}),_jsxs(Accordion,{title:`The speech model was unloaded to free memory (macOS)`,id:`the-speech-model-was-unloaded-to-free-memory-macos`,children:[_jsx(_components.p,{children:`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:`}),_jsxs(_components.blockquote,{children:[`\n`,_jsx(_components.p,{children:`The speech model was unloaded to free memory and couldn’t be reloaded. Close some apps and try again.`}),`\n`]}),_jsx(_components.p,{children:`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.`}),_jsx(_components.p,{children:`HyperWhisper does not retry the transcription automatically. The memory pressure is continuous, so more attempts would only load and lose the model again.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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.`]}),_jsx(Note,{children:_jsxs(_components.p,{children:[`A `,_jsx(_components.a,{href:`/local-api`,children:`Local API`}),` client gets the same condition as the `,_jsx(_components.code,{children:`ENGINE_UNAVAILABLE`}),` error code.`]})})]})]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`permission-\u0026-access-issues`,children:`Permission \u0026 access issues`}),`\n`,_jsx(Heading,{level:`3`,id:`”accessibility-permission-required”`,children:`”Accessibility permission required”`}),`\n`,_jsxs(_components.p,{children:[`Two macOS features need Accessibility permission: `,_jsx(_components.strong,{children:`auto-paste`}),` and `,_jsx(_components.strong,{children:`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.`]}),`\n`,_jsxs(Steps,{children:[_jsx(Step,{title:`Open Accessibility settings`,children:_jsxs(_components.p,{children:[`Go to `,_jsx(_components.strong,{children:`System Settings → Privacy \u0026 Security → Accessibility`}),`.`]})}),_jsx(Step,{title:`Add HyperWhisper`,children:_jsxs(_components.p,{children:[`Click the lock icon and authenticate. Then enable `,_jsx(_components.strong,{children:`HyperWhisper`}),` in the list. macOS does not prompt for this permission. You must add it manually.`]})}),_jsx(Step,{title:`Go back to HyperWhisper`,children:_jsx(_components.p,{children:`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.`})})]}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[`If you use HyperWhisper from Xcode DerivedData and the installed `,_jsx(_components.code,{children:`/Applications/HyperWhisper.app`}),`, the Accessibility list needs two entries, one for each path. The enabled entry must match the build that runs now.`]})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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.`]}),`\n`,_jsxs(_components.p,{children:[`For the full permission overview, see `,_jsx(_components.a,{href:`/permissions`,children:`Permissions`}),`.`]}),`\n`,_jsx(Heading,{level:`3`,id:`”screen-recording-permission-needed”`,children:`”Screen Recording permission needed”`}),`\n`,_jsxs(_components.p,{children:[`Only `,_jsx(_components.strong,{children:`Screen OCR mode`}),` needs Screen Recording permission. This mode reads on-screen text into your transcript context. No other mode needs this permission.`]}),`\n`,_jsxs(_components.p,{children:[`Grant the permission at `,_jsx(_components.strong,{children:`System Settings → Privacy \u0026 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.`]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`network-\u0026-cloud-provider-issues`,children:`Network \u0026 cloud provider issues`}),`\n`,_jsx(Heading,{level:`3`,id:`cloud-transcription-fails`,children:`Cloud transcription fails`}),`\n`,_jsxs(AccordionGroup,{children:[_jsxs(Accordion,{title:`Network connectivity lost`,id:`network-connectivity-lost`,children:[_jsx(_components.p,{children:`HyperWhisper cannot reach the cloud provider.`}),_jsx(_components.p,{children:`The usual symptoms are timeout errors, connection refused, and DNS errors.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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 `,_jsx(_components.a,{href:`https://www.linkedin.com/company/hyperwhisper/`,children:`HyperWhisper’s LinkedIn`}),` for outage announcements.`]})]}),_jsxs(Accordion,{title:`API key missing or invalid`,id:`api-key-missing-or-invalid`,children:[_jsx(_components.p,{children:`A missing or revoked API key causes 401 or 403 HTTP errors.`}),_jsxs(Tabs,{children:[_jsx(Tab,{title:`macOS`,id:`macos-4`,children:_jsxs(_components.p,{children:[`Go to `,_jsx(_components.strong,{children:`Model Library → API Keys`}),`. Make sure that the key for your provider is correct.`]})}),_jsx(Tab,{title:`Windows`,id:`windows-4`,children:_jsxs(_components.p,{children:[`Go to `,_jsx(_components.strong,{children:`Model Library → API Keys`}),`. Make sure that the key is correct.`]})})]}),_jsxs(_components.p,{children:[`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 `,_jsx(_components.a,{href:`/licensing`,children:`HyperWhisper Cloud account key`}),` and your credit balance.`]})]}),_jsxs(Accordion,{title:`HyperWhisper Cloud requires an account key`,id:`hyperwhisper-cloud-requires-an-account-key`,children:[_jsx(_components.p,{children:`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.`}),_jsx(_components.p,{children:`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.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` Open `,_jsx(_components.strong,{children:`Settings → HyperWhisper Cloud`}),`. Then enter your account key, or click `,_jsx(_components.strong,{children:`Get Credits`}),` to buy credits and create a key. Read `,_jsx(_components.a,{href:`/licensing`,children:`Pricing \u0026 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.`]})]}),_jsxs(Accordion,{title:`HyperWhisper Cloud rejects a request with 401 or 403`,id:`hyperwhisper-cloud-rejects-a-request-with-401-or-403`,children:[_jsx(_components.p,{children:`These status codes have different meanings for HyperWhisper Cloud:`}),_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`401`}),` — the account key is invalid or expired. Open `,_jsx(_components.strong,{children:`Settings → HyperWhisper Cloud`}),` and update the key.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`403`}),` — HyperWhisper Cloud temporarily blocked the network. Wait a few minutes, then try again. Changing the account key does not correct this network block.`]}),`\n`]})]}),_jsxs(Accordion,{title:`Insufficient credits or quota exceeded`,id:`insufficient-credits-or-quota-exceeded`,children:[_jsx(_components.p,{children:`Your account has no more credits, or your use is more than the quota of the provider.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`For HyperWhisper Cloud:`}),` Add credits from the billing dashboard. To open the dashboard, go to `,_jsx(_components.strong,{children:`Settings → HyperWhisper Cloud`}),`. For the credit rates, see `,_jsx(_components.a,{href:`/licensing`,children:`Pricing \u0026 Cloud Credits`}),`.`]}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`For BYOK providers:`}),` Log in to the billing page of the provider. Then add credits or increase your quota limit. For the links, see `,_jsx(_components.a,{href:`/choosing-a-provider`,children:`Providers`}),`.`]}),_jsxs(_components.p,{children:[`Some providers report an empty account with an authentication status code. HyperWhisper shows these as this quota error, not as an invalid API key: an ElevenLabs 401 response with `,_jsx(_components.code,{children:`quota_exceeded`}),`, and a SpaceXAI 403 response that says the account used all available credits.`]})]}),_jsxs(Accordion,{title:`Provider temporarily unavailable (server errors)`,id:`provider-temporarily-unavailable-server-errors`,children:[_jsx(_components.p,{children:`The servers of the provider returned a 5xx error. This error is temporary. Your settings did not cause it.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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 `,_jsx(_components.a,{href:`https://www.linkedin.com/company/hyperwhisper/`,children:`HyperWhisper’s LinkedIn`}),` for status updates.`]})]}),_jsxs(Accordion,{title:`Rate limited (429 errors)`,id:`rate-limited-429-errors`,children:[_jsx(_components.p,{children:`You sent requests faster than the provider permits.`}),_jsx(_components.p,{children:`If the provider includes a Retry-After header, HyperWhisper shows the suggested wait duration.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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 `,_jsx(_components.a,{href:`/choosing-a-provider`,children:`Providers`}),`.`]})]})]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`model-download-issues`,children:`Model download issues`}),`\n`,_jsx(Heading,{level:`3`,id:`download-stops-or-does-not-complete`,children:`Download stops or does not complete`}),`\n`,_jsxs(AccordionGroup,{children:[_jsxs(Accordion,{title:`Network connection interrupted`,id:`network-connection-interrupted`,children:[_jsx(_components.p,{children:`If your internet connection stops during a model download, the download can stop before it is complete.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` Make sure that your connection works. Then click `,_jsx(_components.strong,{children:`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.`]})]}),_jsxs(Accordion,{title:`Insufficient disk space`,id:`insufficient-disk-space`,children:[_jsx(_components.p,{children:`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.`}),_jsx(_components.p,{children:`On Windows, HyperWhisper checks the free space before a Whisper or local LLM download starts. It needs the size of the model plus 10%. If there is not enough space, the download does not start, and you see “Not enough disk space to download” with the model name, the space needed, and the space available.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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.`]}),_jsx(_components.p,{children:`HyperWhisper stores the models at:`}),_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`macOS:`}),` `,_jsx(_components.code,{children:`~/Library/Application Support/hyperwhisper/models/`})]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Windows:`}),` `,_jsx(_components.code,{children:`%LOCALAPPDATA%\\\\HyperWhisper\\\\Models\\\\`})]}),`\n`]})]})]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`streaming-issues`,children:`Streaming issues`}),`\n`,_jsx(Heading,{level:`3`,id:`streaming-does-not-work-or-words-do-not-appear`,children:`Streaming does not work or words do not appear`}),`\n`,_jsxs(AccordionGroup,{children:[_jsxs(Accordion,{title:`Streaming is not enabled`,id:`streaming-is-not-enabled`,children:[_jsx(_components.p,{children:`Streaming is off by default. You must enable it before a streaming shortcut or setting becomes active.`}),_jsxs(Tabs,{children:[_jsx(Tab,{title:`macOS`,id:`macos-5`,children:_jsxs(_components.p,{children:[`Open the `,_jsx(_components.strong,{children:`Streaming`}),` section in the sidebar. Then enable the `,_jsx(_components.strong,{children:`Enable Streaming`}),` toggle. The shortcut field and the provider options appear when the toggle is on.`]})}),_jsx(Tab,{title:`Windows`,id:`windows-5`,children:_jsxs(_components.p,{children:[`Click `,_jsx(_components.strong,{children:`Streaming`}),` in the main sidebar. Then select the `,_jsx(_components.strong,{children:`Enable Streaming`}),` checkbox.`]})})]})]}),_jsxs(Accordion,{title:`On-device streaming model not downloaded`,id:`on-device-streaming-model-not-downloaded`,children:[_jsx(_components.p,{children:`You must download the on-device streaming providers before the first use. These providers are Parakeet and Nemotron 3.5, on macOS only.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` In `,_jsx(_components.strong,{children:`Settings → Streaming → Engine`}),`, find the model and click `,_jsx(_components.strong,{children:`Install`}),`. Wait until the download is complete. Then start streaming.`]})]}),_jsxs(Accordion,{title:`Streaming interrupted or cut off mid-sentence`,id:`streaming-interrupted-or-cut-off-mid-sentence`,children:[_jsx(_components.p,{children:`Three conditions can interrupt streaming: a network dropout with a cloud provider, a provider timeout, or an audio input that disconnects during the session.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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.`]})]}),_jsxs(Accordion,{title:`Vocabulary not boosting in streaming`,id:`vocabulary-not-boosting-in-streaming`,children:[_jsxs(_components.p,{children:[`Only `,_jsx(_components.strong,{children:`HyperWhisper Cloud`}),`, `,_jsx(_components.strong,{children:`Deepgram`}),` and `,_jsx(_components.strong,{children:`SpaceXAI`}),` support vocabulary boosting during streaming. HyperWhisper Cloud and Deepgram support it only with an explicit language, not Auto. SpaceXAI accepts the terms with any language. ElevenLabs and OpenAI do not support vocabulary boosting in the streaming API.`]}),_jsx(_components.p,{children:`If you have vocabulary entries and change to a provider without this support, the streaming settings show a warning.`}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` Change to HyperWhisper Cloud, Deepgram or SpaceXAI. For HyperWhisper Cloud and Deepgram, also set an explicit language, not Auto. See `,_jsx(_components.a,{href:`/streaming-settings`,children:`Streaming Transcription`}),`.`]})]}),_jsxs(Accordion,{title:`Deepgram Fast Formatting not behaving as expected`,id:`deepgram-fast-formatting-not-behaving-as-expected`,children:[_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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.`]}),_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` Set the `,_jsx(_components.strong,{children:`Fast Formatting`}),` toggle in the `,_jsx(_components.strong,{children:`Streaming`}),` section. For lower latency, turn it on. For more accurate formatting, turn it off.`]})]})]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`audio-input-\u0026-device-issues`,children:`Audio input \u0026 device issues`}),`\n`,_jsx(Heading,{level:`3`,id:`microphone-input-level-too-low-or-too-high`,children:`Microphone input level too low or too high`}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Fix:`}),` Set the system input volume:`]}),`\n`,_jsxs(Tabs,{children:[_jsx(Tab,{title:`macOS`,id:`macos-6`,children:_jsxs(_components.p,{children:[`Go to `,_jsx(_components.strong,{children:`System Settings → Sound → Input`}),` and select your device. Then speak at your usual dictation level. Increase the `,_jsx(_components.strong,{children:`Input volume`}),` slider until the `,_jsx(_components.strong,{children:`Input level`}),` meter moves to about the middle.`]})}),_jsx(Tab,{title:`Windows`,id:`windows-6`,children:_jsxs(_components.p,{children:[`Right-click the speaker icon in the taskbar → `,_jsx(_components.strong,{children:`Open Sound settings → Sound Control Panel → Recording`}),`. Double-click your microphone. Then open the `,_jsx(_components.strong,{children:`Levels`}),` tab and increase the slider.`]})})]}),`\n`,_jsxs(_components.p,{children:[`HyperWhisper also has an `,_jsx(_components.strong,{children:`Auto-Increase Microphone Volume`}),` option in `,_jsx(_components.strong,{children:`Settings → Sound`}),`. This option increases the input level to 90% at the start of each recording. The change is temporary. See `,_jsx(_components.a,{href:`/audio-input`,children:`Audio Input Volume`}),`.`]}),`\n`,_jsx(Heading,{level:`3`,id:`keep-microphone-warm-has-unexpected-behavior`,children:`Keep Microphone Warm has unexpected behavior`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`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.`]}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsxs(_components.p,{children:[`Enable or disable this option in `,_jsx(_components.strong,{children:`Settings → Sound → Keep Microphone Warm`}),`.`]}),`\n`,_jsx(Note,{children:_jsx(_components.p,{children:`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.`})}),`\n`,_jsx(Heading,{level:`3`,id:`wrong-audio-input-device-selected`,children:`Wrong audio input device selected`}),`\n`,_jsxs(Tabs,{children:[_jsx(Tab,{title:`macOS`,id:`macos-7`,children:_jsxs(_components.p,{children:[`Open `,_jsx(_components.strong,{children:`Settings → Sound`}),` and select the correct device in the `,_jsx(_components.strong,{children:`Microphone`}),` picker. You can also click the HyperWhisper icon in the menu bar, move the pointer over `,_jsx(_components.strong,{children:`Microphone`}),`, and select the device. A checkmark shows the active device.`]})}),_jsx(Tab,{title:`Windows`,id:`windows-7`,children:_jsxs(_components.p,{children:[`Open `,_jsx(_components.strong,{children:`Settings → Sound`}),` and select the correct device in the `,_jsx(_components.strong,{children:`Microphone`}),` picker. You can also right-click the HyperWhisper tray icon, move the pointer over `,_jsx(_components.strong,{children:`Microphone`}),`, and select the device.`]})})]}),`\n`,_jsx(Heading,{level:`3`,id:`audio-device-disconnected-mid-recording`,children:`Audio device disconnected mid-recording`}),`\n`,_jsxs(Tabs,{children:[_jsx(Tab,{title:`macOS`,id:`macos-8`,children:_jsx(_components.p,{children:`If your selected device disconnects during a recording, HyperWhisper keeps your choice. The recording continues on the macOS default input device, in the same file. Later recordings use your device again when it is reconnected.`})}),_jsx(Tab,{title:`Windows`,id:`windows-8`,children:_jsx(_components.p,{children:`If you remove the selected device, HyperWhisper keeps your choice and uses the Windows default input device until the device is reconnected. When the device returns, HyperWhisper matches it by name and changes back to it.`})})]}),`\n`,_jsxs(_components.p,{children:[`Connect the device again. Then make sure that the selection in the Microphone menu is correct before you record again. See `,_jsx(_components.a,{href:`/microphone-selection`,children:`Select a Microphone`}),`.`]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`when-to-contact-support`,children:`When to contact support`}),`\n`,_jsxs(_components.p,{children:[`If these fixes do not correct your problem, send an email to `,_jsx(_components.a,{href:`mailto:hi@support.hyperwhisper.com`,children:`hi@support.hyperwhisper.com`}),`. For a faster diagnosis, include this information:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Your operating system and its version`}),`\n`,_jsxs(_components.li,{children:[`The HyperWhisper version, in `,_jsx(_components.strong,{children:`Settings → General`}),` on macOS, or `,_jsx(_components.strong,{children:`Settings → About`}),` on Windows`]}),`\n`,_jsx(_components.li,{children:`Your provider: a local model, HyperWhisper Cloud, or a BYOK provider`}),`\n`,_jsx(_components.li,{children:`A description of the result and of the result that you expected`}),`\n`]}),`\n`,_jsx(_components.p,{children:`The app log makes the diagnosis much faster:`}),`\n`,_jsxs(Tabs,{children:[_jsxs(Tab,{title:`macOS`,id:`macos-9`,children:[_jsxs(_components.p,{children:[`Open the `,_jsx(_components.strong,{children:`Debug`}),` menu in the menu bar of the app. Select `,_jsx(_components.strong,{children:`Export Update Logs…`}),`. For a more complete bundle, select `,_jsx(_components.strong,{children:`Export Diagnostics…`}),`. Then attach the exported log file.`]}),_jsxs(_components.p,{children:[`If HyperWhisper cannot read its system logs, `,_jsx(_components.strong,{children:`Export Diagnostics…`}),` still saves the file. The alert “Diagnostics Exported Without System Logs” appears, and `,_jsx(_components.code,{children:`system-logs.txt`}),` in the file holds only the reason.`]})]}),_jsx(Tab,{title:`Windows`,id:`windows-9`,children:_jsxs(_components.p,{children:[`Press `,_jsx(_components.code,{children:`Win + R`}),`. Paste `,_jsx(_components.code,{children:`%LOCALAPPDATA%\\\\HyperWhisper\\\\Logs`}),` and press Enter. Then attach the most recent `,_jsx(_components.code,{children:`hyperwhisper-YYYY-MM-DD.log`}),` file.`]})})]}),`\n`,_jsxs(_components.p,{children:[`For more about the information to include and the usual response times, see `,_jsx(_components.a,{href:`/support`,children:`Support \u0026 Refunds`}),`.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Troubleshooting","description":"Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.","href":"/troubleshooting"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Recording issues","slug":"recording-issues","depth":2,"children":[{"title":"App does not record or recording does not start","slug":"app-does-not-record-or-recording-does-not-start","depth":3,"children":[]}]},{"title":"Transcription output issues","slug":"transcription-output-issues","depth":2,"children":[{"title":"No output or blank transcript","slug":"no-output-or-blank-transcript","depth":3,"children":[]}]},{"title":"Permission \u0026 access issues","slug":"permission-\u0026-access-issues","depth":2,"children":[{"title":"”Accessibility permission required”","slug":"”accessibility-permission-required”","depth":3,"children":[]},{"title":"”Screen Recording permission needed”","slug":"”screen-recording-permission-needed”","depth":3,"children":[]}]},{"title":"Network \u0026 cloud provider issues","slug":"network-\u0026-cloud-provider-issues","depth":2,"children":[{"title":"Cloud transcription fails","slug":"cloud-transcription-fails","depth":3,"children":[]}]},{"title":"Model download issues","slug":"model-download-issues","depth":2,"children":[{"title":"Download stops or does not complete","slug":"download-stops-or-does-not-complete","depth":3,"children":[]}]},{"title":"Streaming issues","slug":"streaming-issues","depth":2,"children":[{"title":"Streaming does not work or words do not appear","slug":"streaming-does-not-work-or-words-do-not-appear","depth":3,"children":[]}]},{"title":"Audio input \u0026 device issues","slug":"audio-input-\u0026-device-issues","depth":2,"children":[{"title":"Microphone input level too low or too high","slug":"microphone-input-level-too-low-or-too-high","depth":3,"children":[]},{"title":"Keep Microphone Warm has unexpected behavior","slug":"keep-microphone-warm-has-unexpected-behavior","depth":3,"children":[]},{"title":"Wrong audio input device selected","slug":"wrong-audio-input-device-selected","depth":3,"children":[]},{"title":"Audio device disconnected mid-recording","slug":"audio-device-disconnected-mid-recording","depth":3,"children":[]}]},{"title":"When to contact support","slug":"when-to-contact-support","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"rayamjadltd","siteName":"HyperWhisper","title":"Troubleshooting - HyperWhisper","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-28T23:28:17.085Z","originalFileLocation":"troubleshooting.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.\">\u003cmeta data-mint-head name=\"application-name\" content=\"HyperWhisper\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Troubleshooting - HyperWhisper\">\u003cmeta data-mint-head property=\"og:description\" content=\"Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"HyperWhisper\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://hyperwhisper.com/docs/troubleshooting\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://rayamjadltd.mintlify.site/docs/_mintlify/api/og/v2?division=Troubleshooting\u0026amp;title=Troubleshooting\u0026amp;description=Fixes+for+common+HyperWhisper+problems+%E2%80%94+recording+failures%2C+blank+transcripts%2C+permission+errors%2C+cloud+provider+issues%2C+and+model+downloads.\u0026amp;theme=adc6aad31db440ae29a20d4e\u0026amp;signature=c283fe2dcfe0a4989847ecf8caa67c2db5a1beb9e8c871f6530b03f6cab61f7e\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Troubleshooting - HyperWhisper\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://rayamjadltd.mintlify.site/docs/_mintlify/api/og/v2?division=Troubleshooting\u0026amp;title=Troubleshooting\u0026amp;description=Fixes+for+common+HyperWhisper+problems+%E2%80%94+recording+failures%2C+blank+transcripts%2C+permission+errors%2C+cloud+provider+issues%2C+and+model+downloads.\u0026amp;theme=adc6aad31db440ae29a20d4e\u0026amp;signature=c283fe2dcfe0a4989847ecf8caa67c2db5a1beb9e8c871f6530b03f6cab61f7e\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/rayamjadltd/nSndMpaG8Py431ZB/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"HyperWhisper\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#9810FA\">\u003clink data-mint-head rel=\"canonical\" href=\"https://hyperwhisper.com/docs/troubleshooting\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/troubleshooting.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://hyperwhisper.com/#organization\",\"name\":\"HyperWhisper\",\"url\":\"https://hyperwhisper.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/rayamjadltd/pEagBiOtc1Gduti1/assets/logo.png?fit=max\u0026auto=format\u0026n=pEagBiOtc1Gduti1\u0026q=85\u0026s=febbecb9bbdcca3ff60d262dd6f781d0\"}},{\"@type\":\"WebSite\",\"@id\":\"https://hyperwhisper.com/docs#website\",\"name\":\"HyperWhisper\",\"url\":\"https://hyperwhisper.com/docs\",\"publisher\":{\"@id\":\"https://hyperwhisper.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://hyperwhisper.com/docs/troubleshooting#webpage\",\"url\":\"https://hyperwhisper.com/docs/troubleshooting\",\"name\":\"Troubleshooting\",\"description\":\"Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.\",\"dateModified\":\"2026-10-28T23:28:17.085Z\",\"isPartOf\":{\"@id\":\"https://hyperwhisper.com/docs#website\"},\"breadcrumb\":{\"@id\":\"https://hyperwhisper.com/docs/troubleshooting#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://hyperwhisper.com/docs/troubleshooting#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"HyperWhisper\",\"item\":\"https://hyperwhisper.com/docs\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Troubleshooting\",\"item\":\"https://hyperwhisper.com/docs/troubleshooting\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://hyperwhisper.com/docs/troubleshooting#article\",\"headline\":\"Troubleshooting\",\"name\":\"Troubleshooting\",\"description\":\"Fixes for common HyperWhisper problems — recording failures, blank transcripts, permission errors, cloud provider issues, and model downloads.\",\"url\":\"https://hyperwhisper.com/docs/troubleshooting\",\"mainEntityOfPage\":{\"@id\":\"https://hyperwhisper.com/docs/troubleshooting#webpage\"},\"dateModified\":\"2026-10-28T23:28:17.085Z\",\"publisher\":{\"@id\":\"https://hyperwhisper.com/#organization\"},\"isPartOf\":{\"@id\":\"https://hyperwhisper.com/docs#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"HyperWhisper\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"HyperWhisper\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/docs/troubleshooting.md","siteName":"HyperWhisper","nav":{"global":null,"groups":[{"group":"Getting Started","icon":"rocket","pages":[{"title":"Introduction","href":"/index"},{"title":"System Requirements","href":"/system-requirements"},{"title":"Install HyperWhisper on Linux","href":"/linux-installation"},{"title":"macOS First Run","href":"/macos-first-run"},{"title":"macOS Permissions","href":"/permissions"},{"title":"Best Practices","href":"/best-practices"}]},{"group":"Plans \u0026 Billing","icon":"credit-card","pages":[{"title":"Pricing \u0026 Cloud Credits","href":"/licensing"},{"title":"HyperWhisper Cloud Credits","href":"/cloud-credits"},{"title":"Going Open Source","href":"/going-open-source"}]},{"group":"Transcription \u0026 Models","icon":"microphone-lines","pages":[{"title":"Transcription Modes","href":"/transcription-modes"},{"title":"Models","href":"/models"},{"title":"Providers","href":"/choosing-a-provider"},{"title":"API Keys","href":"/api-keys"},{"title":"Custom OpenAI-Compatible Endpoints","href":"/custom-endpoints"},{"title":"Language \u0026 Detection","href":"/language-detection"}]},{"group":"The Interface","icon":"window-maximize","pages":[{"title":"The Recording Window","href":"/recording-window"},{"title":"Menu Bar \u0026 Tray Controls","href":"/menu-bar"},{"title":"Viewing Transcription History","href":"/history"}]},{"group":"Features","icon":"sparkles","pages":[{"title":"Keyboard Shortcuts \u0026 Accessibility","href":"/keyboard-shortcuts"},{"title":"Auto Paste \u0026 Clipboard Behavior","href":"/auto-paste"},{"title":"Transcribe a File","href":"/file-transcription"},{"title":"Voice Commands","href":"/voice-commands"},{"title":"Voice Coding in AI IDEs","href":"/voice-coding"},{"title":"Streaming Transcription","href":"/streaming-settings"},{"group":"Audio Input","icon":"waveform","pages":[{"title":"Audio Input Volume","href":"/audio-input"},{"title":"Select a Microphone or Audio Input Device","href":"/microphone-selection"},{"title":"Keep Microphone Warm","href":"/keep-microphone-warm"},{"title":"Voice Activity Detection \u0026 Silence Trimming","href":"/voice-activity-detection"},{"title":"Transcribing System Audio","href":"/system-audio"}]},{"group":"Sounds \u0026 Media","icon":"volume-high","pages":[{"title":"Sound Effects","href":"/sound-effects"},{"title":"Mute Audio While Recording","href":"/media-control"}]},{"group":"Vocabulary","icon":"book-open","pages":[{"title":"Custom Vocabulary","href":"/vocabulary"},{"title":"Import \u0026 Export Vocabulary","href":"/vocabulary-import-export"},{"title":"Cloud Sync Vocabulary Across Devices","href":"/vocabulary-cloud-sync"}]}]},{"group":"Settings","icon":"sliders","pages":[{"title":"General Settings","href":"/general-settings"},{"title":"Text Output \u0026 Formatting","href":"/output-settings"},{"title":"Appearance Settings","href":"/appearance-settings"},{"title":"Storage Settings","href":"/storage-settings"},{"title":"Advanced Settings","href":"/advanced-settings"},{"title":"Backup \u0026 Export Settings","href":"/backup-export-settings"}]},{"group":"Privacy \u0026 Security","icon":"shield","pages":[{"title":"Data Privacy","href":"/data-privacy"},{"title":"Network Filtering","href":"/network-filtering"}]},{"group":"Developer \u0026 API","icon":"code","pages":[{"title":"Local API Server","href":"/local-api"},{"title":"Developer Mode","href":"/developer-mode"},{"group":"Local API Reference","icon":"server","pages":[{"title":"Local API Overview","href":"/api-reference/local-api/overview"},{"title":"MCP Setup","href":"/api-reference/local-api/mcp-setup"},{"group":"API Reference","pages":[{"title":"Server + provider snapshot","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml get /health","href":"/api-reference/server-+-provider-snapshot"},{"title":"List models","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml get /models","href":"/api-reference/list-models"},{"title":"List saved Modes","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml get /modes","href":"/api-reference/list-saved-modes"},{"title":"Create a new Mode","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml post /modes","href":"/api-reference/create-a-new-mode"},{"title":"Fetch one Mode","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml get /modes/{id}","href":"/api-reference/fetch-one-mode"},{"title":"Delete a Mode","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml delete /modes/{id}","href":"/api-reference/delete-a-mode"},{"title":"Partial-field update","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml patch /modes/{id}","href":"/api-reference/partial-field-update"},{"title":"Transcribe audio","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml post /transcribe","href":"/api-reference/transcribe-audio"},{"title":"Rewrite text with AI post-processing","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml post /post-process","href":"/api-reference/rewrite-text-with-ai-post-processing"},{"title":"Search past transcripts","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml get /recordings/search","href":"/api-reference/search-past-transcripts"},{"title":"Search past transcripts (alias)","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml get /recordings","href":"/api-reference/search-past-transcripts-alias"},{"title":"Fetch one recording","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml get /recordings/{id}","href":"/api-reference/fetch-one-recording"},{"title":"Start the microphone, or stop it and transcribe","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml post /recording/toggle","href":"/api-reference/start-the-microphone-or-stop-it-and-transcribe"},{"title":"Stop the microphone and keep no transcript","description":"Works on Linux only. macOS does not serve this path. Windows answers it with\n`ok: false` and the code `ENGINE_UNAVAILABLE`. The route takes no\nrequest body. It stops the recorder at any point and writes no\ntranscript.\n","deprecated":null,"version":null,"openapi":"/api-reference/local-api/openapi.yaml post /recording/cancel","href":"/api-reference/stop-the-microphone-and-keep-no-transcript"}]}]}]},{"group":"Troubleshooting","icon":"life-ring","pages":[{"title":"Troubleshooting","href":"/troubleshooting"},{"title":"Fixing Transcription Hallucinations","description":"Why speech-to-text models invent words, and how you can decrease it.","href":"/hallucinations"},{"title":"Performance Tips","href":"/performance-tips"},{"title":"Provider Health \u0026 Automatic Failover","href":"/provider-health"},{"title":"App Updates","href":"/updates"},{"title":"Support \u0026 Refunds","href":"/support"}]},{"group":"Windows","icon":"windows","pages":[{"title":"Windows Getting Started","href":"/windows-getting-started"},{"title":"Windows Permissions","href":"/windows-permissions"},{"title":"Windows FAQ","href":"/windows/faq"}]}]},"basePath":"","title":"Troubleshooting - HyperWhisper","buildId":"dpl_H5KQTnCewfWWvJxA7c3bCm7MFbb6","deploymentId":"dpl_H5KQTnCewfWWvJxA7c3bCm7MFbb6","dynamics":[],"chunks":[]}