Troubleshooting

Debug Mode

Enable debug mode to see detailed logs. See the Debug page for how to enable it and where to find log files.

Common Issues

Handy is not transcribing anything

  • Check that your microphone is not muted at the system level
  • Make sure a model has been downloaded (check Settings > Models)
  • Try switching to a different microphone in Settings > General
  • Enable debug mode and check the logs for errors

Text is not being pasted

  • Make sure your cursor is in a text field before starting transcription
  • Try switching the paste method in Settings > Advanced (see Paste Methods)
  • On macOS, ensure Handy has Accessibility permissions (System Settings > Privacy & Security > Accessibility)
  • On Linux, check your typing tool configuration (see Paste Methods > Typing Tools)
  • Try increasing the paste delay in Debug settings

Wrong text is being pasted

If Handy pastes your previous clipboard contents instead of the transcription, increase the paste delay in Debug settings. The default is 60ms; try 100-200ms.

Slow transcription

  • Try a smaller model (Moonshine Tiny or Whisper Small)
  • Check that GPU acceleration is being used (visible in debug logs)
  • Close other GPU-intensive applications
  • Configure the model unload timeout in Advanced settings

Microphone not detected

  • Check system audio settings to ensure the mic is recognized
  • Try unplugging and reconnecting the microphone
  • Use the refresh button next to the microphone dropdown in Settings > General
  • On Linux, check that PulseAudio or PipeWire is running

Whisper crashes

Whisper models can crash on certain hardware configurations, particularly older CPUs and some Windows/Linux systems. If Whisper crashes:

  1. Use Parakeet V3 instead - it is the most stable model and recommended for English
  2. Try a smaller Whisper model (Small instead of Medium or Large)
  3. Update your GPU drivers (Vulkan support is required)
  4. Run with --debug to capture crash details for bug reports

vulkan-1.dll not found (Windows)

Update your GPU drivers (NVIDIA, AMD, or Intel). Vulkan is required for GPU acceleration. If your GPU is too old to support Vulkan, Handy may not work on your system.

Garbled text with non-QWERTY keyboards

If Handy outputs garbled text when you use AZERTY, QWERTZ, or other non-US keyboard layouts, you are likely using the Direct Input paste method. Switch to a clipboard-based paste method. See Paste Methods for details.

Blank window on Linux

On some Linux systems, Handy may show a blank window due to a WebKit DMA-BUF rendering issue. Recent versions of Handy set WEBKIT_DISABLE_DMABUF_RENDERER=1 automatically. If you are on an older version, set this environment variable manually:

WEBKIT_DISABLE_DMABUF_RENDERER=1 handy

AppImage GLIBC error (Linux)

The AppImage requires GLIBC 2.38+. Ubuntu 22.04 ships with GLIBC 2.35 and is incompatible. Solutions:

  • Use the .deb package instead of the AppImage
  • Upgrade to Ubuntu 24.04+ or another distribution with GLIBC 2.38+

Overlay steals focus on Linux

On some Linux desktop environments, the Handy overlay takes focus away from the target window, preventing paste. Set Overlay Position to None in Settings > Advanced. See Advanced > Overlay Position.

Wayland overlay not showing

The Wayland overlay requires gtk-layer-shell as a runtime dependency:

  • Debian/Ubuntu: sudo apt install libgtk-layer-shell0
  • Arch: sudo pacman -S gtk-layer-shell
  • Fedora: sudo dnf install gtk4-layer-shell

Note: On KDE Wayland, gtk-layer-shell initialization is skipped to prevent overlay issues.

Failed model download

If a model download fails partway through and you cannot re-download it:

  1. Go to About > App Data Directory
  2. Navigate to the models/ folder
  3. Delete any partially downloaded files
  4. Restart Handy and try the download again

Platform-Specific Notes

macOS

  • Handy requires Accessibility and Microphone permissions
  • If Handy cannot paste, re-add it in System Settings > Privacy & Security > Accessibility
  • Metal GPU acceleration is used automatically
  • Install via Homebrew: brew install --cask handy

Windows

  • Run the installer as administrator if you encounter permission issues
  • Vulkan drivers are required for GPU acceleration
  • Make sure your audio drivers are up to date
  • If Handy cannot paste into apps running as administrator, run Handy as administrator too
  • For pasting into terminals (CMD, PowerShell), use the Shift+Insert paste method

Linux

  • AppImage requires FUSE (sudo apt install libfuse2 on Ubuntu/Debian)
  • Wayland users should configure a typing tool for paste to work
  • X11 generally works out of the box
  • Vulkan drivers are needed for GPU acceleration (vulkan-tools to verify)
  • Control Handy from scripts/WMs using signals or CLI flags
  • Set overlay to None if it steals focus from the target window

Known Issues

  • Whisper instability on certain hardware - Whisper models may crash on older CPUs or specific GPU configurations. Use Parakeet V3 as a stable alternative.
  • Linux audio playback in history - Audio playback of recorded history entries may not work on some Linux configurations.

Getting Help

If you are still stuck: