Solutions to the most common OpenFlow issues. If your problem is not listed here, open an issue on GitHub and include the steps to reproduce it.

Microphone & audio

No microphone detected

Check your operating system's microphone permissions for OpenFlow:

  • Windows: Settings > Privacy & Security > Microphone — ensure OpenFlow is allowed.
  • macOS: System Settings > Privacy & Security > Microphone — enable OpenFlow.
  • Linux: Verify your microphone is the default input in PulseAudio/PipeWire, and that no other app has exclusive access.

In Settings > Models, confirm the correct input device is selected.

Audio sounds fine but nothing is transcribed

  • Make sure a transcription model is downloaded and selected in Settings > Models.
  • Try the rule-based cleanup path by disabling the local LLM server temporarily.
  • Check that the audio device is not muted or set to 0% volume.

Hotkey

Hotkey not working

Another app or desktop environment may be using the same shortcut. Change it in Settings > General.

On Linux, global shortcuts depend on your desktop environment. If the hotkey does not register, try a different combination or check whether your compositor is capturing it first.

Hotkey triggers but text is not pasted

System-wide paste is fully supported on Windows. On macOS and Linux, system-wide paste and transforms are still being completed — build from source for the latest progress. As a workaround, OpenFlow can copy the result to your clipboard so you can paste manually.

Models

Parakeet won't install

Automatic Parakeet installation is currently Windows-only. On Windows, make sure you have at least 2.5 GB of free disk space. OpenFlow automatically uses the fixed drive with the most free space if your system drive is low.

If installation fails partway, restart OpenFlow and try again — the installer verifies SHA-256 checksums before extracting, so partial downloads are retried safely.

Whisper model download fails

Downloads can fail on slow or unstable connections. Retry from Settings > Models. The Tiny model (75 MB) is the smallest and most reliable to fetch.

Local LLM server not found

Make sure llama-server is running on http://127.0.0.1:8080/v1. You can verify it with:

curl http://127.0.0.1:8080/v1/models

If the server is not running, OpenFlow automatically falls back to rule-based cleanup — dictation still works, just with simpler text refinement.

To force a specific Whisper backend for debugging, set OPENFLOW_WHISPER_BACKEND before launching:

$env:OPENFLOW_WHISPER_BACKEND = "whisper.cpp"
npm run tauri dev

Build & development

Build errors

  1. Run npm install to make sure all dependencies are present.
  2. Update the Rust toolchain with rustup update.
  3. Make sure you meet the prerequisites: Node.js 18+, Rust 1.70+, and the Tauri CLI.
  4. On Linux, install the Tauri system dependencies:
sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

npm run tauri dev crashes on startup

  • Check that no other instance of OpenFlow is already running.
  • Delete the cached build output and try again: remove src-tauri/target/debug/ and re-run.
  • On Windows, ensure the Visual Studio C++ build tools are installed.

Data & storage

Where is my data stored?

All data lives in a local SQLite database:

  • Windows: %APPDATA%\openflow\openflow.db
  • macOS: ~/Library/Application Support/openflow/openflow.db
  • Linux: ~/.local/share/openflow/openflow.db

Models are stored under the models/ subdirectory of the same app-data folder.

How do I reset everything?

Open Settings > Data & Privacy > Clear Data, or manually delete the database file. Restart OpenFlow and it will recreate a fresh database on next launch.

Still stuck?