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 pull <model> to fetch the model, for example dictare models pull whisper-large-v3-turbo.
  • Python version mismatch: Dictare uses Python 3.11 from its runtime store. Check ~/.local/share/dictare/current/bin/python --version. If you installed from source, 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 -a dictare. After setup, ~/.local/bin/dictare and /opt/homebrew/bin/dictare may both exist. That is normal: Homebrew owns the entry point, while Dictare owns the runtime. If the active path points inside .pyenv, a project .venv, or an old Cellar runtime, a stale binary is shadowing the managed runtime.

  2. Check the active runtime:

readlink ~/.local/share/dictare/current
  1. Repair the installed service and launcher:
dictare repair
  1. If MLX extras are missing, reinstall the active runtime with MLX support:
dictare upgrade --reinstall --extras mlx
  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 and relaunch. Accept it, then run dictare repair.
  3. Right Cmd key: The default hotkey is Right Command. Make sure you're pressing the right one.

Linux

On Wayland, your user must be in the input group:

groups $USER | grep input
sudo usermod -aG input $USER
# Log out and back in

The default hotkey is Scroll Lock. Not all keyboards have this key; remap in config:

[hotkey]
key = "KEY_CAPSLOCK"  # or another key

Keyboard Mode Not Working

If Dictare transcribes your voice but nothing is typed into the focused window, check the platform-specific injection requirement.

  • macOS: Go to System Settings > Privacy & Security > Accessibility. Ensure Dictare.app is listed and enabled.
  • Linux/Wayland: install and run ydotool, and make sure your user can access /dev/uinput.

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:

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.
  • Reduce background noise: Move closer to the microphone, use a headset, or reduce ambient noise

Set the language explicitly instead of "auto":

[stt]
language = "en"

Add hotwords for technical terms and names that are often misrecognized. Hotwords are supported by FasterWhisper on Linux/Intel Mac, but not by MLX Whisper or Parakeet.

[stt.advanced]
hotwords = "pytest, FastAPI, OpenVIP, Dictare"

If transcriptions are cut off, increase the silence threshold:

[audio]
silence_ms = 1200  # Default is 850

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 the current voice target: Use the tray current-agent menu, say agent <session-name>, or press the claim key (Ctrl+\) in the intended terminal
  4. Check output mode: Ensure mode = "agents" in config.
[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.
[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/OuteTTS: Requires the engine service and any needed model cache. Check with dictare models list and download with dictare models pull <model>.
  • No audio output: Check your output device in config and system audio settings

High CPU Usage

  • TTS engine: Kokoro and outetts use more CPU than espeak or say

For large models on CPU, switch to a smaller model or enable hardware acceleration:

[stt]
model = "small"  # Instead of large-v3
hw_accel = true

[stt.advanced]
device = "auto"
compute_type = "int8"  # Lower precision, faster

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