Troubleshooting
Most problems are one of six: the text went to another window, the first take after a break was slow, AirPods recorded nothing, the indicator vanished after a fullscreen app, a quiet take came back as “Didn't catch that”, or a ⌥ shortcut started a recording. Each has a cause and a fix below — several were bugs that recent versions removed, so update first.
The text landed in the wrong window
Writing a take down takes a fraction of a second to several, and in that gap a notification you glanced at, an app raising a window, or a Space switch could take the front — so the paste went there. Since 1.7.3 FreeFlow remembers the app you were dictating into the moment you stop speaking and brings it back before pasting. If it cannot (the app quit, macOS refused), the take stays on your clipboard for thirty seconds and the indicator says so. On older versions: update, and use Copy Last Transcript to recover the take.
The first take after a break sits on “Writing it down…” for ten seconds
macOS paged the speech model's weights out of memory while FreeFlow sat idle, and the transcriber pulled them back from disk one page at a time. Since 1.5.2 FreeFlow re-reads the model's files in one pass while you are still speaking if the model has been idle for ten minutes, so the weights are back before you release ⌥. If you still see it, the Mac is very short of memory or the model is on a slow external disk.
Nothing is recorded with AirPods or a Bluetooth headset
Two causes. Before 1.7.2, macOS's audio engine kept pulling the capture onto the headset's microphone a few milliseconds after each start, flipping the headset into its call profile and killing the take before a single sample — fixed by opening the chosen microphone directly. Separately, Auto-detect prefers the built-in microphone whenever the system input is a Bluetooth headset, on purpose, so the headset keeps its stereo. Want the headset mic anyway? Pick it under Settings → While dictating → Microphone.
A notification sound ended my recording
On any microphone that is also an output — AirPods, most audio interfaces, every aggregate device — a chime, or any app starting playback, made macOS re-state the device's sample rate, and FreeFlow read that as “the microphone died”. Fixed in 1.7.3: only a real unplug, re-clock or channel change stops a recording now.
The indicator does not appear, but text still arrives
After leaving a fullscreen app on a Mac with several Spaces, macOS quietly removed the indicator's window from every other Space and never put it back — the pill was there, on a Space you were not looking at. Fixed in 1.7.2: the indicator and the Claude card move to the active Space each time they appear and follow you if you switch. A related 1.7.1 fix stops App Nap from dozing the app so a take begun from idle always shows its indicator.
“Didn't catch that” on a quiet take, or “Thank you.” from silence
The silence gate looks for a moment of actual speech-level sound rather than averaging the whole take, so an empty hold pastes nothing instead of the model's favourite hallucination, “Thank you.” If your quiet speech trips it, lower Settings → While dictating → Silence threshold. If your first syllable is clipped, lengthen Hold-⌥ delay in the same place.
A ⌥ shortcut opened the microphone, ducked my music, flashed the indicator
Fixed in 1.5.1. Holding ⌥ now waits 150 ms before it touches anything, so ⌘⌥←, ⌥⌫ and ⌥e never reach the microphone. On AirPods each of those flips used to drop the headset into mono; that is gone too. If a chord still triggers a take, your other tool is sending ⌥ on its own — pick a different hold key under Settings → Hotkeys.
My volume stayed low after dictating
Ducking lowers other audio while you speak and puts it back after. It used to put it back only if the level was exactly where FreeFlow had left it, and a Bluetooth headset renegotiating its level was enough to strand it at 25%. Since 1.5.1 it comes back unless you turned it up yourself mid-take, and every duck and restore is written to the log outside Incognito.
English came out in Cyrillic, or the wrong language
Parakeet V3 guesses the language from the audio and a one-word take gave it nothing to go on. Set the mode's language (Modes → Language) and, from 1.7.1, the model stays in that alphabet. See languages.
Settings… in the menu bar does nothing
After a login launch, the window those items open had never been created. Fixed in 1.7.1: FreeFlow builds its window on demand, so the menu bar, Finder and Spotlight all open it from the first click.
Dictating into a password field left the text on my clipboard
macOS blocks pasting into password fields, so FreeFlow leaves the text on the clipboard for you to paste yourself. It is cleared after 30 seconds whether or not Incognito is on (since 1.5.0). If Accessibility is off, or the keystroke could not be sent, the same 30-second clipboard hold applies.
Nothing pastes anywhere
- System Settings → Privacy & Security → Accessibility: FreeFlow must be on. Toggle it off and on after an update if a paste stops landing.
- System Settings → Privacy & Security → Microphone: FreeFlow must be on, and System Settings → Sound → Input must point at a microphone that actually hears you — watch the level bar.
- A clipboard manager that re-reads the pasteboard on every change can race the paste. FreeFlow marks its paste so well-behaved managers skip it; a few do not.
A Claude Code card never shows
Settings → Claude Code says “Not connected” after FreeFlow.app has been moved: click Connect again. The whole list of causes is on the hook page.
Still stuck
Help → Send Feedback, with diagnostics on. The toggle names exactly what is in them before you send, and a screenshot goes only if you drop one in. A person reads it, usually within a day. scripts/verify-install.sh on the FreeFlow repository is a read-only diagnostic that prints facts about an install and changes nothing, if support asks you to run it.
Questions people ask
Where does FreeFlow keep its log?
In ~/Library/Application Support/FreeFlow/ beside your history, as a plain text file. Outside Incognito it records each take's timing and every duck and restore.
Does updating lose my modes or dictionary?
No. They are files in Application Support, untouched by an update. The updater replaces the app bundle only.
Dictation works in TextEdit but not in one app
That app is likely denied the Microphone permission (which does not matter to FreeFlow) or is an Electron app with a non-standard field. Try clicking into the field first; if a paste still fails, the take is on your clipboard for 30 seconds — paste it yourself.