Troubleshooting

Common issues and their solutions.

Installation Issues

pyaudio install fails

Cause: Missing PortAudio system library.

Fix:

Windows

pip install pipwin
pipwin install pyaudio

Debian / Ubuntu

sudo apt-get install portaudio19-dev python3-pyaudio

macOS

brew install portaudio

mss or pyautogui import error

Fix:

pip install mss pyautogui

Runtime Issues

No audio playback

Cause: Missing playback backend.

Fix: Install ffplay (via ffmpeg) or mpv:

Windows

1. Download ffmpeg from ffmpeg.org
2. Add bin folder to PATH
3. Verify: ffplay -version

macOS

brew install ffmpeg

Linux

sudo apt-get install ffmpeg
# or
sudo pacman -S ffmpeg

Hotkey not working

Wake word not detected

Cause: Missing PORCUPINE_ACCESS_KEY for custom models.

Fix:

• Built-in "computer" keyword works without a key
• Custom models require PORCUPINE_ACCESS_KEY
• Check microphone permissions

STT / LLM calls hang

Run with --verbose for detailed error output:

voiceuse --verbose

Window focus fails on Linux

Cause: xdotool not installed or Wayland incompatibility.

Fix:

sudo apt-get install xdotool wmctrl

Low confidence on vision clicks

Grok Voice plugin won't start

Getting Help

If your issue isn't listed here:

1. Run with --verbose and check the output
2. Check GitHub Issues
3. Open a new issue with:
   • Your OS and Python version
   • Your config.yaml (with API keys redacted)
   • The exact error message
   • Steps to reproduce