Troubleshooting

This guide covers common issues and their solutions, organized by category.

Microphone Issues

Microphone Not Detected

Check system permissions

macOS
Windows
Linux

Open System Settings → Privacy & Security → Microphone
Ensure OpenWhispr is checked
If not listed, click the lock icon and add OpenWhispr manually
Restart OpenWhispr

Check PulseAudio/PipeWire permissions:

# List audio devices
pactl list sources

# If using PipeWire
pw-cli ls Node

Test microphone in browser

Navigate to https://webcammictest.com/check-mic.html and verify your microphone works in Chrome/Edge.If it doesn’t work in browser, the issue is system-level (not OpenWhispr-specific).

Check FFmpeg availability

Open DevTools (Cmd/Ctrl+Shift+I) in Control Panel and run:

await window.electronAPI.checkFFmpegAvailability()

Expected output:

{
  "available": true,
  "path": "/path/to/ffmpeg",
  "version": "6.0"
}

Enable debug logging

Open Control Panel → Settings → Advanced
Enable “Debug Logging”
Try recording again
Click “Open Logs Folder” and check main.log for errors

Common issue: Browser-based microphone access requires HTTPS or localhost. Electron uses localhost in development, so this should not be a problem.

No Audio Detected

Symptom: Recording completes but 'No audio detected' error

Possible causes:

Microphone muted: Check system volume mixer
Wrong input device: Select correct device in System Settings → Sound
Extremely quiet audio: Increase microphone gain
FFmpeg conversion failure: Audio didn’t convert to WAV properly

Debug:

# Enable debug logging and check for FFmpeg errors:
# Look for lines like:
# [audioManager] FFmpeg conversion failed: ...
# [audioManager] Audio level: 0.00 (too quiet)

Fix:

Increase microphone input volume
Test with ffmpeg -f avfoundation -i ":0" -t 5 test.wav (macOS)
Test with ffmpeg -f dshow -i audio="Microphone" -t 5 test.wav (Windows)

Symptom: 'MediaRecorder not supported' error

Cause: Browser/Electron version too old or missing codecsFix:

Update OpenWhispr to latest version (includes latest Electron)

Verify Electron version:

console.log(process.versions.electron); // Should be 36.9.5+

Check supported MIME types:

MediaRecorder.isTypeSupported('audio/webm'); // Should be true

Transcription Failures

Local Whisper Transcription Fails

Verify whisper.cpp binary

# Check if binary exists
ls -la resources/bin/whisper-cpp-*

# On macOS, check for ARM vs Intel
file resources/bin/whisper-cpp-darwin-arm64
# Output: Mach-O 64-bit executable arm64

# Test binary directly
./resources/bin/whisper-cpp-darwin-arm64 --help

If binary is missing:

npm run download:whisper-cpp

Check model download

# List downloaded models
ls -lh ~/.cache/openwhispr/whisper-models/

# Verify file size matches expectedSizeBytes
stat -f%z ~/.cache/openwhispr/whisper-models/ggml-base.bin
# Should output: 148000000 (148 MB)

If model is missing or corrupted:

# Delete and re-download
rm ~/.cache/openwhispr/whisper-models/ggml-base.bin
# Then download via Control Panel → Models

Test whisper.cpp manually

# Create test audio
ffmpeg -f lavfi -i "sine=frequency=1000:duration=5" -ar 16000 test.wav

# Run whisper
./resources/bin/whisper-cpp-darwin-arm64 \
  -m ~/.cache/openwhispr/whisper-models/ggml-base.bin \
  -f test.wav \
  -l en

# Should output transcription or error message

Check debug logs

Look for errors like:

whisper.cpp: error loading model
whisper.cpp: failed to decode audio
FFmpeg conversion failed

Common fixes:

Re-download model
Verify FFmpeg is working
Check disk space (models are 75MB-3GB)

Cloud Transcription Fails

OpenAI API Key Invalid

Error: Invalid API key or 401 UnauthorizedFix:

Verify API key at https://platform.openai.com/api-keys
Check API key format: sk-proj-... (new format) or sk-... (legacy)
Ensure billing is active (https://platform.openai.com/account/billing)
Re-save key in Control Panel → Settings → API Keys

Test key manually:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

# Should return list of models, not error

Rate Limit Exceeded

Error: 429 Too Many RequestsCause: OpenAI free tier limits or quota exhaustedFix:

Wait 60 seconds and retry
Upgrade OpenAI plan: https://platform.openai.com/account/billing/overview
Switch to local transcription (no rate limits)

Check quota:

curl https://api.openai.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Network / Proxy Issues

Symptom: ECONNREFUSED, ETIMEDOUT, or Network errorDebug:

Test internet connectivity:

curl -I https://api.openai.com
# Should return HTTP 200 or 301

Check corporate firewall/proxy settings
Try with VPN disabled (some VPNs block OpenAI)

Proxy configuration:

# Set proxy in environment
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# Then restart OpenWhispr

Clipboard / Pasting Issues

macOS: Text Not Pasting

Grant accessibility permissions

Open System Settings → Privacy & Security → Accessibility
Enable OpenWhispr
If not listed, click + and add OpenWhispr
Restart OpenWhispr

Accessibility permission is required for AppleScript-based auto-paste to work.

Test clipboard manually

Record a short dictation
Open TextEdit or any text field
Press Cmd+V

If text pastes manually but not automatically, it’s a permission issue.

Check debug logs

Look for:

[clipboard] Accessibility permission denied
[clipboard] AppleScript paste failed: ...

If you see “permission denied”, re-check System Settings.

Windows: Text Not Pasting

PowerShell execution policy

Symptom: Paste fails silentlyCause: PowerShell execution policy blocks SendKeysFix:

# Check current policy
Get-ExecutionPolicy

# If "Restricted", change to RemoteSigned
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Alternative: Use windows-fast-paste.exe (downloaded automatically)

nircmd.exe missing

Symptom: Logs show nircmd.exe not foundFix:

npm run download:nircmd

Or download manually:

URL: https://www.nirsoft.net/utils/nircmd.html
Extract nircmd.exe to resources/bin/nircmd.exe

Linux: Text Not Pasting

Check paste tool availability

# X11: xdotool (primary method)
which xdotool

# Wayland: wtype or ydotool
which wtype
which ydotool

# If none found, install one:
sudo apt install xdotool  # Debian/Ubuntu
sudo dnf install xdotool  # Fedora

Test native paste binary

# Check if compiled
ls -la resources/bin/linux-fast-paste

# Test manually
echo "test" | xclip -selection clipboard
resources/bin/linux-fast-paste
# Should paste "test" to focused window

GNOME Wayland users

Native Wayland apps (not XWayland) may not support auto-paste.Workaround:

Use Ctrl+V manually
Or use XWayland-based apps (most Electron apps run via XWayland)

ydotool daemon (if using ydotool)

# Start daemon
sudo systemctl enable --now ydotoold

# Check status
systemctl status ydotoold

Hotkey Conflicts

Hotkey Not Registering

Symptom: 'Hotkey already in use' warning

Cause: Another app is using the same hotkeyFix:

Open Control Panel → Settings → Hotkey
Change to a different key combination
Common alternatives: F8, F9, Cmd+Shift+Space, Ctrl+Alt+R

macOS conflicts:

Backtick (`): Spotlight or Raycast
Cmd+Space: Spotlight
Globe/Fn: System emoji picker (macOS 13+)

Windows conflicts:

Win+G: Xbox Game Bar
Win+Shift+S: Snipping Tool

GNOME Wayland: Hotkey not working

Cause: Electron’s globalShortcut API doesn’t work on WaylandSolution: OpenWhispr automatically uses native GNOME shortcutsVerify:

Open GNOME Settings → Keyboard → Keyboard Shortcuts → Custom Shortcuts
Look for “OpenWhispr Toggle Dictation”
If missing, restart OpenWhispr

Limitations:

Push-to-talk not supported (only tap-to-talk)
Some keys unavailable (e.g., backtick `)

Windows Push-to-Talk Not Working

Symptom: Tap works but push-to-talk doesn’t respondCause: Native key listener binary missing or failedFix:

# Re-download binary
npm run download:windows-key-listener

# Or check if it exists
ls resources/bin/windows-key-listener.exe

Fallback: If binary can’t be obtained, use tap-to-talk mode

Model Download Problems

Download Stalls or Fails

Check network connectivity

# Test HuggingFace connectivity
curl -I https://huggingface.co

# Test whisper.cpp model URL
curl -I https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin

Clear partial downloads

# Delete incomplete files
rm ~/.cache/openwhispr/whisper-models/*.tmp
rm ~/.cache/openwhispr/whisper-models/*.partial

Check disk space

# Ensure enough space for model
df -h ~/.cache/openwhispr

# Large model needs 3GB free:
# - large-v3: 3GB
# - turbo: 1.6GB
# - medium: 1.5GB

Try manual download

# Download with curl (resume supported)
curl -L -C - -o ~/.cache/openwhispr/whisper-models/ggml-base.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin

# Verify file size
ls -lh ~/.cache/openwhispr/whisper-models/ggml-base.bin

Model File Corrupted

Symptom: 'Failed to load model' error

Cause: Download interrupted or file corruptedFix:

# Delete corrupted model
rm ~/.cache/openwhispr/whisper-models/ggml-base.bin

# Re-download via Control Panel
# Or manually:
curl -L -o ~/.cache/openwhispr/whisper-models/ggml-base.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin

# Verify size matches expectedSizeBytes
# base model should be exactly 148000000 bytes

Debug Mode

Enable comprehensive logging for troubleshooting:

Enable via UI

Open Control Panel → Settings → Advanced
Toggle Debug Logging on
Reproduce the issue
Click Open Logs Folder

Enable via environment variable

# Add to .env file
OPENWHISPR_LOG_LEVEL=debug

# Or set temporarily
export OPENWHISPR_LOG_LEVEL=debug
npm run dev

Log file locations

macOS
Windows
Linux

~/Library/Logs/OpenWhispr/main.log

%USERPROFILE%\AppData\Roaming\OpenWhispr\logs\main.log

~/.config/OpenWhispr/logs/main.log

Read logs

# View last 100 lines
tail -n 100 ~/Library/Logs/OpenWhispr/main.log

# Follow in real-time
tail -f ~/Library/Logs/OpenWhispr/main.log

# Search for errors
grep -i error ~/Library/Logs/OpenWhispr/main.log

What’s logged in debug mode:

Audio pipeline (MediaRecorder → FFmpeg → whisper.cpp)
IPC calls and responses
File system operations
Network requests (API calls, downloads)
Error stack traces

Performance Issues

Slow Transcription (Local)

Large model on slow CPU

Symptom: Transcription takes 30+ seconds for 10 seconds of audioFix:

Switch to smaller model: base (142MB) or tiny (75MB)
Use cloud transcription (OpenAI API)
Enable GPU acceleration (if supported):
- macOS: Automatic (Metal)
- Windows/Linux: CUDA (requires NVIDIA GPU)

Memory usage high

Symptom: OpenWhispr uses 500MB+ RAMCause: Large model loaded in memoryFix:

Use smaller model

Stop whisper-server when not in use:

await window.electronAPI.whisperServerStop();

Restart app to clear memory

High CPU Usage

whisper.cpp pegging CPU

Normal behavior: Transcription uses 100% of available coresIf it persists after transcription:

Check if whisper-server is stuck:

await window.electronAPI.whisperServerStatus()

Stop server:

await window.electronAPI.whisperServerStop()

Restart OpenWhispr

Getting Help

If none of the above solutions work:

Gather information

OS: macOS 13.4 / Windows 11 / Ubuntu 22.04
OpenWhispr version: Control Panel → About
Error message: Exact text or screenshot
Debug logs: Last 50 lines from log file

Search existing issues

Check GitHub Issues: https://github.com/OpenWhispr/openwhispr/issuesUse search terms like:

“microphone permission”
“whisper.cpp failed”
“paste not working”

Create new issue

If not already reported:

Go to https://github.com/OpenWhispr/openwhispr/issues/new

Use template:

**Describe the bug**
[Clear description]

**To Reproduce**
1. Open app
2. Record dictation
3. Error appears

**Expected behavior**
[What should happen]

**Environment**
- OS: [e.g., macOS 14.2]
- Version: [e.g., 1.5.5]

**Debug logs**

[Paste relevant log lines]

Do NOT include API keys, passwords, or personal information in GitHub issues. Redact them from logs before posting.

Common Error Messages

Error Message	Cause	Solution
`Microphone permission denied`	macOS/Windows microphone privacy setting	Grant permission in System Settings
`No audio detected`	Microphone muted or gain too low	Increase input volume
`whisper.cpp binary not found`	Missing or wrong platform binary	Run `npm run download:whisper-cpp`
`Failed to load model`	Model file corrupted or missing	Delete and re-download model
`Invalid API key`	Wrong or expired OpenAI key	Update key in Settings
`Rate limit exceeded`	Too many API requests	Wait 60s or upgrade plan
`Accessibility permission required`	macOS paste needs permission	Enable in System Settings → Accessibility
`xdotool not found`	Linux paste tool missing	`sudo apt install xdotool`
`Hotkey already in use`	Conflict with another app	Change hotkey in Settings
`FFmpeg not found`	Bundled FFmpeg failed to unpack	Reinstall OpenWhispr

Platform-Specific Notes

macOS
Windows
Linux

Common Issues:

Globe key listener requires Xcode Command Line Tools
Accessibility permission needed for paste
Notarization may cause “damaged” errors on unsigned builds

Fix “App is damaged”:

xattr -cr /Applications/OpenWhispr.app

Common Issues:

Multiple paste tool options (xdotool, wtype, ydotool)
GNOME Wayland requires D-Bus shortcuts
Some distros need manual dependency installation

Install dependencies:

# Debian/Ubuntu
sudo apt install xdotool wl-clipboard ydotool

# Fedora
sudo dnf install xdotool wl-clipboard ydotool

Next Steps

Architecture

Deep dive into technical internals

Model Registry

Manage AI models and downloads

Building from Source

Compile and customize OpenWhispr

Get Started

Core Features

Configuration

Platform Guides

Advanced

Microphone Issues

Microphone Not Detected

No Audio Detected

Transcription Failures

Local Whisper Transcription Fails

Cloud Transcription Fails

Clipboard / Pasting Issues

macOS: Text Not Pasting

Windows: Text Not Pasting

Linux: Text Not Pasting

Hotkey Conflicts

Hotkey Not Registering

Model Download Problems

Download Stalls or Fails

Model File Corrupted

Debug Mode

Performance Issues

Slow Transcription (Local)

High CPU Usage

Getting Help

Common Error Messages

Platform-Specific Notes

Next Steps

Architecture

Model Registry

Building from Source

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Platform Guides

Advanced

​Microphone Issues

​Microphone Not Detected

​No Audio Detected

​Transcription Failures

​Local Whisper Transcription Fails

​Cloud Transcription Fails

​Clipboard / Pasting Issues

​macOS: Text Not Pasting

​Windows: Text Not Pasting

​Linux: Text Not Pasting

​Hotkey Conflicts

​Hotkey Not Registering

​Model Download Problems

​Download Stalls or Fails

​Model File Corrupted

​Debug Mode

​Performance Issues

​Slow Transcription (Local)

​High CPU Usage

​Getting Help

​Common Error Messages

​Platform-Specific Notes

​Next Steps

Architecture

Model Registry

Building from Source

Build docs developers (and LLMs) love

Microphone Issues

Microphone Not Detected

No Audio Detected

Transcription Failures

Local Whisper Transcription Fails

Cloud Transcription Fails

Clipboard / Pasting Issues

macOS: Text Not Pasting

Windows: Text Not Pasting

Linux: Text Not Pasting

Hotkey Conflicts

Hotkey Not Registering

Model Download Problems

Download Stalls or Fails

Model File Corrupted

Debug Mode

Performance Issues

Slow Transcription (Local)

High CPU Usage

Getting Help

Common Error Messages

Platform-Specific Notes

Next Steps