Troubleshoot the setup in the order AFK uses it.

The model is still preparing

First-run setup downloads and optimizes the speech model. Check that the Mac is online, that there is roughly 2 GB of free disk space, and that AFK remains open while setup runs. The setup screen can retry after a failed download.

If the model is ready in the app but a dictation says it is still setting up, wait for the status to settle and try again. The CLI also prepares the model on its first invocation.

License activation fails

Confirm that you pasted the key from the purchase email without extra spaces and that the Mac can reach Polar. A malformed or unknown key is different from a temporary network error. The app can continue without activating after a failed attempt, so you can retry later.

Activation sends the key to Polar's customer-portal endpoint; it does not send your audio.

The hotkey does nothing

1. Open System Settings → Privacy & Security → Accessibility and ensure AFK is enabled.
2. Check Microphone permission in the same Privacy & Security area.
3. Return to AFK. It polls permission state and tries to arm the global listener again.
4. Hold the configured key, not necessarily the default Right Option key if you changed it in Settings.

Accessibility is needed for both the global event tap and typing into other apps. Microphone is needed to capture the recording.

The transcript is not appearing in the app

Check whether the focused element is actually editable. AFK pastes into a known editable field. For an unknown or non-editable target, it keeps or places the transcript on the clipboard so you can paste manually. You can also enable Always copy to clipboard instead of typing in Settings.

If the transcript is on the clipboard, click the intended field and press Command + V. If no text appears anywhere, check Microphone permission and the speech model status first.

Hands-free mode starts or stops unexpectedly

Hands-free starts only while the dictation key is held and the full start sequence is pressed. The default start sequence is A-F-K. The default stop action is the dictation key plus Return. Both sequences are configurable, so inspect Settings if the on-screen hint does not match your memory. Escape cancels an active recording.

An audio file will not transcribe

• Confirm the model is ready.
• Start with one supported audio file: .m4a, .wav, .mp3, .aiff, .aif, .caf, or .flac.
• Try opening or playing the file in a Mac audio app first. AFK relies on macOS audio reading and conversion.
• If one queued job fails, remove it and try again. Other queued jobs can continue.

For the exact file flow, see Transcribe audio. The current site documents audio inputs only.

A finished result disappeared

Non-empty file results that were not saved expire from the local cache one hour after completion. Save the result from the card before that countdown ends. Once saved, the file is yours and History keeps a reference to it.

The CLI prints the wrong thing

• Check the alias points to /Applications/AFK.app/Contents/MacOS/AFK, or invoke that path directly.
• Use the form afk transcribe file.m4a. Put the audio path as the first bare argument.
• Transcript output is stdout. Model progress and errors are stderr, so redirect or pipe stdout deliberately.
• Use --srt or --json for structured output, --v2 for the English-only model, and --lang en or another ISO 639-1 hint with v3.

On the first CLI run, model preparation may need the network. Once ready, recognition is local. See the full CLI reference.

Updates are not checking

AFK uses Sparkle for in-app update checks. A failed update check does not change local dictation or transcription. Check your connection and try again later; the updater is separate from the speech-processing path.