Back to docs

Common Issues

Transcription is not working

Symptoms: Recording stops but no text appears; the app shows a transcription error.

Causes and fixes:

  1. Invalid or missing API key — Open Settings and verify your OpenAI API key is entered correctly. It must start with sk- and be at least 20 characters. Re-paste the key and save.

  2. Insufficient API quota — Your OpenAI account may have hit its usage limit. Log in to platform.openai.com and check your usage and billing under Usage.

  3. No microphone input — The recording may have captured silence. Check that the correct microphone is selected as the default input device in your OS sound settings.

  4. No internet connection — Transcription requires a live connection to the OpenAI API. Verify your internet connection.

Dictation hotkey is not working

Symptoms: Pressing Ctrl+Shift+Space does nothing.

Causes and fixes:

  1. Another app has the hotkey — A different application (screenshot tool, password manager, system utility) may have registered the same key combination. Change the dictation hotkey in Settings to something unique.

  2. Accessibility permission denied (macOS) — Global hotkeys require Accessibility access on macOS. See macOS Setup.

  3. App not running — The app must be running (even minimised to the tray) for hotkeys to work.

  4. Hotkey registration failed silently — Save your Settings again with the same or a new hotkey to force re-registration.

App shows "OpenAI API key required" warning

The yellow warning banner means no valid API key is stored. Navigate to the Settings tab, enter your key, and click Save Settings. The banner clears automatically.

Microphone permission denied

Windows:

  1. Open Settings → Privacy & Security → Microphone.
  2. Ensure "Microphone access" is on and that Voice Recorder Forge is allowed.

macOS:

  1. Open System Settings → Privacy & Security → Microphone.
  2. Enable Voice Recorder Forge.
  3. Restart the app.

Text is not inserted at cursor after dictation

Windows: If text is not inserted automatically, check that the target application accepts keyboard-simulated paste. Try a different text field.

macOS: Automatic text insertion is not yet supported on macOS. The transcript is copied to the clipboard — paste it manually with Cmd+V. See the macOS Setup page for current macOS limitations.

Meeting recording produces no transcript

  1. Ensure the recording lasted long enough for Whisper to process (at least a few seconds of audible speech).
  2. Confirm your microphone was active and not muted.
  3. Check the OpenAI API key and quota as described above.

App crashes or will not launch

  1. Delete the app data directory and relaunch (this resets all settings — you will need to re-enter your API key):
    • Windows: %APPDATA%\VoiceAssistant\
    • macOS: ~/Library/Application Support/VoiceAssistant/
  2. Reinstall the application.
  3. If building from source, ensure you are running Node.js 20+ and have run npm install.

System tray icon is not visible

On Windows, the system tray overflow area may be hiding the icon. Click the ^ arrow in the taskbar notification area to find the icon. You can drag it to the visible area to pin it.