Dictare / Docs / Troubleshooting

Troubleshooting

Service Won't Start

Check the service status and logs:

dictare service status
dictare logs --last 50

Common causes:

  • Port already in use: Another process is using port 8770. Check with lsof -i :8770 and stop the conflicting process.
  • Missing STT model: Run dictare models download to fetch the model.
  • Python version mismatch: Dictare uses Python 3.11 (installed automatically by Homebrew on macOS or the install script on Linux). If you installed from source, ensure you use uv run --python 3.11.

STT Running on CPU Instead of MLX (macOS)

If dictare status shows large-v3-turbo on cpu instead of on mlx on Apple Silicon:

  1. Check which binary is being used: run which dictare. It should show /opt/homebrew/bin/dictare. If it shows a path containing .pyenv or .local/bin, a stale binary is shadowing the Homebrew one.

  2. Fix: remove the stale binary and rehash:

rm $(which dictare)    # remove the stale binary
pyenv rehash           # if using pyenv
  1. Reinstall the service (so launchd picks up the correct binary):
dictare service uninstall
dictare service install
  1. Verify: dictare status should now show on mlx.

Hotkey Not Working

macOS

  1. Input Monitoring permission: Go to System Settings > Privacy & Security > Input Monitoring. Ensure Dictare.app is listed and enabled.
  2. If Input Monitoring doesn't work: Select Dictare.app in the list, click the minus (−) button at the bottom left to remove it, then click plus (+) to re-add it. Browse to ~/Applications/Dictare.app. macOS will ask you to "Quit & Relaunch" — accept it, then restart the service: dictare service restart.
  3. Right Cmd key: The default hotkey is Right Command. Make sure you're pressing the right one.

Linux

  1. Input group: On Wayland, your user must be in the input group: bash groups $USER | grep input sudo usermod -aG input $USER # Log out and back in
  2. Scroll Lock key: The default hotkey is Scroll Lock. Not all keyboards have this key; remap in config: toml [hotkey] key = "KEY_CAPSLOCK" # or another key

Keyboard Mode Not Working

If Dictare transcribes your voice but nothing is typed into the focused window, you're missing the Accessibility permission.

Go to System Settings > Privacy & Security > Accessibility. Ensure Dictare.app is listed and enabled. This permission is required for keyboard mode to inject keystrokes into other applications.

No Audio Input

# Check audio devices
dictare setup
  • Verify the correct input device is selected in config.toml or the web dashboard
  • Test your microphone with another app first
  • Check system audio settings (input volume, mute state)

macOS

  • Microphone permission: Go to System Settings > Privacy & Security > Microphone. Ensure Dictare.app is listed and enabled.
  • If using an external microphone, ensure it's selected as the system input device
  • Check System Settings > Sound > Input

Linux

  • Check PulseAudio/PipeWire: bash pactl list sources short
  • Ensure the user has audio group access

Transcription Quality Issues

  • Try a different model: Switch between large-v3-turbo, large-v3, and parakeet-v3 to find what works best for your accent and language.
  • Set the language: Instead of "auto", set an explicit language hint: toml [stt] language = "en"
  • Add hotwords (FasterWhisper on Linux/Intel Mac only): Technical terms and names that are often misrecognized. Not supported by MLX Whisper or Parakeet. toml [stt.advanced] hotwords = "pytest, FastAPI, OpenVIP, Dictare"
  • Reduce background noise: Move closer to the microphone, use a headset, or reduce ambient noise
  • Check silence threshold: If transcriptions are cut off, increase the silence threshold: toml [audio] silence_ms = 1200 # Default is 850, increase if transcriptions are cut off

Agent Not Receiving Input

  1. Check the service is running: dictare status
  2. Check the agent is connected: The status output shows connected agents
  3. Check focus: The active terminal must have focus, or use the claim key (Ctrl+\)
  4. Check output mode: Ensure mode = "agents" in config: toml [output] mode = "agents"

Web Dashboard Not Loading

The dashboard runs at http://localhost:8770/ui. If it's not loading:

  1. Check the service is running: dictare service status
  2. Check the port isn't blocked: curl http://localhost:8770/openvip/status
  3. Check server config: toml [server] host = "127.0.0.1" port = 8770

TTS Not Working

# List available engines
dictare speak --list-engines

# Test with the simplest engine
dictare speak "test" --engine espeak
  • macOS: The say engine should work out of the box
  • Linux: Install espeak-ng for the espeak engine
  • Kokoro/Piper: Requires model download via dictare models
  • No audio output: Check your output device in config and system audio settings

High CPU Usage

  • Large models on CPU: Switch to a smaller model or enable hardware acceleration: ```toml [stt] model = "small" # Instead of large-v3 hw_accel = true

[stt.advanced] device = "auto" compute_type = "int8" # Lower precision, faster `` - **TTS engine**: Kokoro and outetts use more CPU thanespeakorsay`

Logs

View logs for debugging:

# Follow live logs
dictare logs -f

# Last 100 lines
dictare logs --last 100

# Filter by component
dictare logs --name pipeline
dictare logs --name stt

# TTS-specific logs
dictare logs --tts

# Raw format (no formatting)
dictare logs --raw

Reset Configuration

If your config is broken, move it aside and start fresh:

mv ~/.config/dictare/config.toml ~/.config/dictare/config.toml.bak
dictare setup

Getting Help