Common issues and fixes

If something isn't working, start here. Grouped by symptom.

Quick diagnostic

Microphone issues

"No audio detected"

1. Right device selected? Settings → Microphone, confirm input device. Click Refresh if missing.
2. Level meter moves? Speak — bar should move. If flat, it's an OS issue. Check System Settings → Sound → Input.
3. Other apps holding the mic? Zoom, Teams, and some recording apps lock the mic exclusively. Quit them.
4. Permission granted? System Settings → Privacy & Security → Microphone — Whiskers must be enabled.

Mic permission missing or denied

System Settings → Privacy & Security → Microphone. Enable Whiskers.

If Whiskers isn't in the list, press the dictation hotkey once and macOS will add it.

Nuclear option (resets every app's mic permission):

tccutil reset Microphone

Bluetooth mic drops or stutters

• Stay within ~10 ft of the Mac.
• Charge the device fully.
• Avoid using it as both input and output simultaneously.

Hotkey issues

Hotkey does nothing

1. Accessibility permission. System Settings → Privacy & Security → Accessibility — confirm Whiskers is enabled. Toggle off and on if it is, then restart Whiskers.
2. Another app owns the shortcut. Try a different key in Settings → Hotkeys to isolate.
3. Restart Whiskers. macOS occasionally loses track of registered hotkeys after sleep/wake.

Text doesn't paste

Transcription completes (HUD shows "Processing") but nothing appears.

1. Accessibility again — same permission for both detection and paste. Toggle off/on, restart Whiskers.
2. Text field actually focused? Click into the field before triggering.
3. Check the clipboard. Text is still there — Cmd+V to paste manually.
4. Some apps block programmatic paste. Test in Notes or TextEdit to isolate.

Permissions

Granted but not working

Common after macOS updates. Toggle the permission off and back on in System Settings, then restart Whiskers.

Keep resetting

If you regrant a permission and it reverts:

1. Reinstall Whiskers — delete from Applications, empty Trash, install fresh, regrant during onboarding.
2. Last resort, reset the whole TCC bucket (affects all apps):

tccutil reset Accessibility
tccutil reset Microphone

Transcription issues

Empty transcripts

HUD completes but nothing pastes; history shows empty entries.

1. Check mic input (see above).
2. Lower VAD sensitivity. Settings → Microphone → Voice Activity Detection — try 30–40%. Aggressive VAD filters quiet speech as silence.
3. Try a different model. Some local models handle quiet audio better. Switch in Settings → Models.
4. Speak louder and closer to the mic.

Poor accuracy

1. Language set explicitly? Don't use auto-detect if you know the language. Settings → Models → Language.
2. Bigger model. Parakeet V2 is English-only — if your audio isn't English, switch to Parakeet V3 (25 languages) or Whisper Large v3 (99+ languages). For English, Parakeet V2 is usually fine.
3. Add custom vocabulary. Names, jargon, product terms — Settings → Dictionary. See Features → Vocabulary.
4. Reduce background noise.
5. Use a better mic. A $50 USB mic dramatically improves accuracy in noisy environments.

Wrong language detected

Auto-detect picked wrong. Switch to explicit language in Settings → Models → Language.

If using Parakeet V2 (English only), confirm your audio actually is in English.

Model issues

Download fails

Models are 75 MB – 3 GB.

1. Free disk space. Aim for 5 GB. Models go in ~/Library/Application Support/Whiskers.
2. Stable connection. Mobile hotspots and flaky Wi-Fi cause partial downloads.
3. Quit and reopen Whiskers, click Download again. Whiskers resumes most downloads.

Model won't load after download

"Model error" even though it shows as downloaded:

1. Remove and re-download for a fresh copy.
2. Check free RAM — Whisper Large v3 wants ~6 GB. Close other apps if you're on an 8 GB Mac.
3. Try a smaller model. Large v3 is sometimes too much for older Apple Silicon.

Cloud API errors

Auth failures, rate limits, "API error":

1. Verify the key. Settings → API Keys — open the key, compare against the provider's dashboard.
2. Check provider billing. Out-of-credit accounts return the same auth errors as invalid keys.
3. Provider outage. Check their status page.
4. Switch providers. If you have a backup key, swap and keep working.

AI Enhancement issues

Enhancement on but text isn't being enhanced

1. Model status. Settings → AI Enhancement — card should say "Ready," not "Setup Required."
2. Active key valid. Settings → API Keys for that provider. If you have multiple, you may have an invalid one selected.
3. Internet up. AI Enhancement always requires network.
4. Toggle off/on. Resets internal state.

Over-editing, wrong tone, hallucinations

1. Lighter prompt. "Clean Transcript" preserves voice; "Professional Rewrite" doesn't.
2. Different model. GPT-4o-mini and Claude Haiku are more conservative than larger frontier models.
3. Write a custom prompt. Built-ins are starting points — a tailored prompt almost always beats them for your use case.
4. Disable for sensitive content. Toggle off in the menu bar for technical or legal text.

General

High CPU or memory

• Smaller model. Whisper Large v3 is the heaviest; Whisper Medium or Small are leaner.
• Whiskers unloads idle models after 2 minutes. CPU spikes between sessions are the model loading; subsequent uses calm down.

App crashes or freezes

1. Force quit (Option + Cmd + Esc) and relaunch.
2. Check for updates — crashes are often already fixed.
3. Submit feedback via Settings → Support, toggle "Include logs."

Still stuck

• Confirm latest version.
• Restart Whiskers, then restart your Mac.
• Settings → Support with logs attached.