Troubleshooting
Most problems are one of a handful of things: the paste couldn't land, the desktop hasn't granted a permission, or a key or microphone isn't set up. Start with the message the capsule showed you.
On Linux, open voisu or run voisu doctor first. It checks the daemon, the shortcut and RemoteDesktop portals, the clipboard and your keys, and tells you what to do about anything that fails. voisu doctor --verbose shows the reasoning behind each check.
The Trigger Key does nothing (Linux)
- Check the daemon is running:
voisu status, orsystemctl --user status voisu.service. - Check which key was approved:
voisu shortcut. - On KDE Plasma and GNOME, the shortcut is chosen in a desktop dialog the first time the daemon starts. If you dismissed it, restart the daemon with
systemctl --user restart voisu.serviceto see it again. - On Hyprland, run
voisu setupagain to reinstall the bind. - On X11 (Cinnamon, Linux Mint, Ubuntu on X11) there is no shortcut dialog. Bind
voisu toggleunder Keyboard → Shortcuts → Custom Shortcuts. voisu doctorreports a portal that has no usable global-shortcuts support.
Voisu isn't running after login (Linux)
The daemon waits up to 20 seconds for your desktop session to come up. If voisu service status still shows it inactive or failed, start it once the desktop is ready and check its log:
$ voisu service restart $ journalctl --user -u voisu.service
On Windows, turn on Start at login in the tray menu or settings window.
Wayland portal permissions (Linux)
On Wayland, Voisu asks the desktop for permission through portals instead of reading your keyboard directly. It never needs root or uinput access.
- Global Shortcuts gives Voisu its Trigger Key.
- Remote Desktop lets Voisu press paste for you when Delivery is
paste. Your desktop asks once and Voisu remembers the grant.
If you refused the Remote Desktop prompt, or want to be asked again, reset the grant Voisu saved:
$ rm ~/.local/state/voisu/remote-desktop.restore-token $ systemctl --user restart voisu.service
This clears only Voisu's own saved grant. A permission your desktop remembers by itself isn't cleared by this.
On GNOME, a few voisu doctor results are expected: Paste action and Paste backend show SKIP (they're Hyprland checks), and Focus guard shows WARN because GNOME can't report the focused window. The capsule is the overlay@voisu.app Shell extension there, so an inactive voisu-overlay.service is normal.
Keys
- “Add your Groq and Deepgram keys to start dictating.” Windows needs both keys. Open Settings… and add them.
- A key fails validation. Check you copied the whole key, and that it's still active in the provider's console.
- Linux:
voisu auth verify groqorvoisu auth verify deepgramchecks a saved key with its provider.
Microphone (Windows)
- No microphone found. Connect one, or choose a default input device in Settings → System → Sound.
- Windows is blocking the microphone. Open Settings → Privacy & security → Microphone and turn on Let desktop apps access your microphone.
- The microphone stopped working. The device went away mid-Recording, for example a headset that disconnected. Reconnect it and try again.
The paste didn't land
Your words are kept either way. On Windows, copy them from the Last Transcript card on the Overview tab (Settings… in the tray). On Linux they're on your clipboard.
| Windows message | What it means |
|---|---|
| Can't type into an admin window | See Admin windows. |
| Click into another app first | The Recording started while a Voisu window had focus. Click where you want the text, then dictate. |
| The window you were typing in closed | The window that had focus when you started is gone. Copy the Transcript from Last transcript. |
| Couldn't return to your window | Windows wouldn't bring the original window back to the front. |
| Another app replaced the clipboard; nothing pasted | A clipboard manager or another app wrote to the clipboard mid-paste. Copy from Last transcript and try again. |
Use Test paste (in 3 s) in the tray to check one app on its own: click into it within three seconds and watch whether the sample text appears.
Linux terminals. On GNOME, Voisu pastes by sending Ctrl V. A terminal that pastes with Ctrl Shift V receives nothing, but the Transcript is on the clipboard, so paste it yourself.
Linux, GNOME. GNOME doesn't let Voisu check which window has focus, so paste lands in whatever window has focus when you stop. To paste by hand instead, switch with voisu delivery copy.
Admin windows (Windows)
Windows doesn't let an ordinary app type into a window running as administrator, such as an elevated terminal, Task Manager or an installer. It drops the keystrokes silently, so Voisu checks first and shows Can't type into an admin window instead of pretending it worked.
Copy the Transcript from Last transcript and paste it yourself, or run the target app without elevation.
SmartScreen (Windows)
The installer isn't code-signed yet, so Microsoft Defender SmartScreen may show “Windows protected your PC” the first time you run it. Choose More info, then Run anyway. The installer comes from the project's GitHub releases, and updates after that are signature-checked before they install.
Reporting a bug
Open an issue on GitHub with your OS, desktop and what the capsule said. On Linux, voisu history lists recent Recordings with their IDs, and voisu export <id> writes a redacted export of one you can attach. On Windows, the log folder is shown at the bottom of the settings window.
Nothing is sent anywhere unless you attach it yourself.