Handy not working: the fixes for shortcuts, pasting, models and microphones

By · Published

When Handy stops working it is usually one of four things: the shortcut is not reaching it, the text is not being pasted, the model did not download, or the microphone is wrong. On a Mac, check first that Handy still has Accessibility and Microphone access, then find your symptom below.

I built YapToText, a dictation app for the Mac, so read what I say about Handy with that in mind. Every fact about Handy here comes from its documentation at handy.computer and its README on GitHub, read on October 11, 2026.

Download YapToText on the Mac App StoreThis app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.

On this page: 11 sections
  1. Find your symptom
  2. Nothing is transcribed
  3. The shortcut stopped working on a Mac
  4. Text is not pasted
  5. Your old clipboard text is pasted
  6. A model will not download
  7. Slow, crashing, or the wrong microphone
  8. Linux startup problems
  9. Where to get help
  10. The short version
  11. Questions

Find your symptom

From Handy's troubleshooting page and README, read October 11, 2026.

What you seeMost likely causeFirst thing to try
Nothing is transcribedNo model, or the wrong microphoneSettings, Models, then Settings, General
The shortcut does nothing on a MacSecure Input, or Fn on a third-party keyboardCheck the warning banner in settings
Text is not pastedNo Accessibility access, or the paste methodRe-add Handy under Accessibility
Old clipboard text is pastedThe clipboard is restored too soonRaise the paste delay in Debug
A model will not downloadA partial file, or a blocked networkDelete the partial file and retry
Whisper crashesThe hardwareSwitch to Parakeet V3

Nothing is transcribed

  • Check the microphone. Make sure it is not muted at the system level, and try another one in Settings, General. The refresh button beside the list rescans for devices.
  • Check the model. Settings, Models should show a downloaded model.
  • Read the logs. Open Handy's settings and press Cmd Shift D on a Mac, or Ctrl Shift D on Windows and Linux, to reveal Debug.

The shortcut stopped working on a Mac

If a shortcut with a regular key, such as Option Space, suddenly stops while a modifier-only shortcut still works, the cause is probably Secure Input. It is the macOS mechanism that protects password fields, and while it is active macOS stops delivering some key events. Handy's docs say recent versions detect it, show a warning banner in settings that names the process when it can, and switch affected shortcuts to a fallback.

  • Terminal or iTerm2. Turn off Secure Keyboard Entry in the application menu.
  • Password managers. Quit or update them. The docs say some releases are known to hold Secure Input in the background.
  • A stuck login window. Press Ctrl Cmd Q to lock the screen, then log in by typing your password, not with Touch ID. If that fails, log out and back in.

To see which process holds Secure Input, the docs give this command, and note that macOS reports it on a best-effort basis:

ioreg -l -w 0 | grep -o 'kCGSSessionSecureInputPID"=[0-9]*' | grep -o '[0-9]*' | head -1 | xargs ps -o pid,comm -p

A shortcut that is only a modifier, such as Fn alone, keeps working through Secure Input, so it is a good push-to-talk choice if this happens often. Recording a new shortcut is disabled until Secure Input clears.

Fn on a third-party keyboard. Fn reaches macOS only from Apple keyboards. Other keyboards handle it in their own firmware and send nothing, so Handy has no event to hear. Use Control, Option, Shift, Command or a regular key instead.

Text is not pasted

  • Cursor. Make sure it is in a text field before you start.
  • Accessibility on a Mac. Open System Settings, Privacy and Security, Accessibility. If Handy is listed and still cannot paste, remove it and add it again.
  • Paste method. Try another one in Settings, Advanced.
  • Paste delay. Raise it in the Debug settings.
  • Windows. Run Handy as administrator, and switch Keyboard Implementation to Tauri Global Shortcut under Advanced, Experimental. For CMD and PowerShell, use the Shift Insert paste method.
  • Linux. Install a typing tool: xdotool on X11, wtype or dotool on Wayland. Set Overlay Position to None if the overlay takes focus from the window you are typing in.
  • Garbled text on AZERTY or QWERTZ. You are probably on the Direct Input paste method. Switch to a clipboard-based one.

Your old clipboard text is pasted

The transcription is right in History, but Handy pastes something you copied earlier. With the standard paste method Handy restores your previous clipboard after a fixed delay, and a busy app can read the clipboard after that has happened.

  1. Open Handy's settings and press Cmd Shift D to reveal Debug.
  2. On a Mac or Windows, try Reliable Paste (Beta) with a clipboard paste method selected. The README calls it experimental.
  3. Otherwise raise Paste Delay (After). The docs give 60 ms as the default and suggest 100 to 200 ms.

A model will not download

  1. Open About and click App Data Directory. On a Mac it is ~/Library/Application Support/com.pais.handy/.
  2. Open the models folder and delete any partly downloaded file.
  3. Restart Handy and download again.

Behind a proxy or firewall, the README says you can download the model file in a browser and place it in that models folder yourself, without renaming it, then restart Handy. It lists the address of each file.

Stuck on the setup screen. Quit Handy, open settings.json in the same app data folder, set "onboarding_completed": true, save, and start Handy again.

Slow, crashing, or the wrong microphone

  • Slow transcription. Try a smaller model, such as Moonshine Tiny or Whisper Small, close other apps that use the GPU, and check the model unload setting in Advanced.
  • Whisper crashes. The docs say Whisper models can crash on some hardware, and name Parakeet V3 as the most stable model. A smaller Whisper model is the other option.
  • Bluetooth headset on a Mac. Playback quality can drop while you record, because Bluetooth switches to two-way audio. Keep the headphones as output and choose the built-in or an external microphone in Handy.
  • Microphone not detected. Reconnect it and press the refresh button in Settings, General.

Linux startup problems

  • Crashes at launch or no window. Install or reinstall gtk-layer-shell. It is libgtk-layer-shell0 on Ubuntu and Debian.
  • Still failing. Start it with HANDY_NO_GTK_LAYER_SHELL=1 handy.
  • Blank window. Older versions need WEBKIT_DISABLE_DMABUF_RENDERER=1 handy. Recent versions set it themselves.
  • AppImage GLIBC error. The AppImage needs GLIBC 2.38 or later, which Ubuntu 22.04 does not have. Use the .deb, or a newer release.
  • Global shortcuts on Wayland. Bind handy --toggle-transcription as a custom shortcut in your desktop environment.

Where to get help

Handy's docs point to its Discord, to GitHub issues for bugs, and to [email protected]. Say which version, operating system, model and paste method you use.

If you are on an Apple silicon Mac and would rather not debug, YapToText is the free app I built. It comes from the Mac App Store with its speech model included, so there is no model download to fail, and its trigger is a tap of Right Command. It does not run on Windows, Linux or Intel Macs, where Handy does. The Handy guide covers setup, and the Handy alternative page compares the two.

Download YapToText on the Mac App StoreThis app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.

The short version

  • Shortcut dead on a Mac. Secure Input. Check the banner in settings, or use a modifier-only shortcut.
  • Nothing pasted. Accessibility access, then the paste method.
  • Old clipboard pasted. Raise Paste Delay (After) to 100 to 200 ms.
  • Download fails. Delete the partial file in the models folder.
  • Whisper crashes. Use Parakeet V3.

If a fix here no longer matches Handy, open an issue on GitHub and I will update this page. Every one gets read.

Download YapToText on the Mac App StoreThis app is completely free. You don't have to make an account. There are no subscriptions, no difficult downloads, and nothing is locked. Made for Apple silicon Macs. Source on GitHub.

About the author. Ryleigh Newman is a developer whose hands make typing difficult and who dictates every day with YapToText, the app this site describes. Facts about other apps come from their own sites, with the date they were read. More about the project.

Sources

Questions

Why is my Handy shortcut not working on a Mac?

Usually Secure Input, which macOS turns on for password fields and some terminals and password managers. Handy shows a warning banner in settings. A modifier-only shortcut keeps working.

Why does Handy paste my old clipboard?

Handy restores your previous clipboard after a fixed delay, and a busy app can read it too late. Raise Paste Delay (After) in Debug, or try Reliable Paste.

Why does the Fn key not trigger Handy?

Fn only reaches macOS from Apple keyboards. A third-party keyboard handles Fn in its firmware and sends nothing to the Mac.

How do I open Handy's debug settings?

Open Handy's settings window and press Cmd Shift D on a Mac, or Ctrl Shift D on Windows and Linux.

What do I do when a Handy model download fails?

Open the App Data Directory from About, delete the partial file in the models folder, restart Handy, and download again.