14 · Support

Troubleshooting

Fix recording, permission, and text insertion problems.

Quick Diagnosis

Start with these checks:

Check permission status in Settings → Permissions.
Run Settings → Speech model → Test Setup.
Dictate once in a code editor and once in a terminal.
Open History and check the insertion status for your latest entries.

Use the results to distinguish a recording or transcription failure from an insertion failure.

Test setup transcribes a short test clip with the main engine and the fallback tool and reports each step. Follow it with a dictation to check recording and insertion. When the Dictate tab offers Review settings, it opens the Settings page that fixes the problem. Save any error messages before changing settings or restarting. Steno can lose quiet opening words after a long silence, and Small can mishear words.

Common Issues

Symptom	Likely cause	Fix
Option key does nothing	Input Monitoring denied or hotkey monitor stale	Grant Input Monitoring, re-check in Settings → Permissions, relaunch Steno
Option shortcut such as Option+Arrow doesn't start a recording	Expected: Steno ignores keyboard shortcuts that use Option and quick taps of Option	Hold Option on its own to dictate
Dictation says microphone access is off	Microphone access is turned off	Grant Microphone in System Settings → Privacy & Security
Hands-free key fails	Function key not assigned or conflicts with another shortcut	Pick a key in Settings → Recording (F1–F12 need standard function-key mode; F13–F20 need a keyboard or mapping that can send the key)
Transcription works, no text appears	Accessibility denied or wrong insertion order	Grant Accessibility and verify Text Output order
Steno reports Copied instead of inserting	The cursor was in a password or secure field, focus moved during transcription, or no text field was selected	Click the intended field and press Cmd+V, or copy the text from History
Terminal output is inconsistent	The terminal may not handle simulated typing reliably	Keep clipboard fallback enabled; Steno already prioritizes clipboard for known terminal bundle IDs
Onboarding Continue is disabled	Microphone not granted	Grant Microphone in System Settings → Privacy & Security, or choose Set up later; recording still requires microphone access
`File not found at this path` (Engine)	Bundled or local paths can't be resolved	DMG: reinstall the latest DMG. Source: rebuild whisper.cpp at the pinned version
Model download fails	The download failed or didn't match the published file	Read the reason next to the Download button; the current model stays in use
Dictation key ignored right after changing the model or thread count	Known issue: the speech model reloads after a transcription setting changes, and a key pressed during that short reload is ignored	Press the key again once the reload finishes
Media settings unavailable	Media pausing requires macOS 15 or later	Update macOS; your saved choice is kept
Safari media keeps playing during dictation	Known issue: Safari plays audio through a system helper process Steno cannot yet tie to the app	See Media Settings
Media you paused resumes after a dictation	Known issue: you resumed and paused it again during the dictation, or macOS reported playback state unreliably and the video was paused less than about two seconds before dictating	See Media Settings

Fixes for DMG Users

If you installed Steno from the official DMG, try these in order:

Move Steno.app to your Applications folder if it isn't already there — apps run outside Applications can hit permission and signing edge cases on macOS.
Reinstall the latest DMG from the release page if you suspect bundled files are damaged.
Re-check Microphone, Accessibility, and Input Monitoring in System Settings → Privacy & Security.
Open Settings → General, turn on Open the setup guide, then choose Save changes; the guide opens when you save.
Open Settings → Speech model and use the Model Library to download a different model (for example, switch back to Small to confirm baseline behavior).
Run Test Setup. If it still fails, copy the error text into your issue report.

Fixes for Source-Build Contributors

If you built Steno from source:

Rebuild whisper.cpp at the pinned version:

cd vendor/whisper.cpp
git checkout 764482c3175d9c3bc6089c1ec84df7d1b9537d83
cd ../..
scripts/build-whisper-runtime-helper.sh

Regenerate the Xcode project after project.yml changes:
```
xcodegen generate
```
Run from Xcode (Cmd+R) and confirm signing/team settings haven't reset macOS TCC grants.
Confirm whisper-cli --help runs from the exact path configured in Settings → Speech model.
Check whether the issue is global or app-specific by dictating into an editor, a terminal, and a browser text field.

Advanced Debugging

If the checks above do not resolve the issue:

Compare insertion outcomes across editor, terminal, and browser to isolate app-specific behavior.
Confirm code-signing identity hasn't changed unexpectedly (that resets TCC grants).
Check History — completed entries can preserve the transcript, so you can recover the text even when insertion fails.

Before Reporting

Include this in your issue:

macOS version
Steno version (and whether you installed from the DMG or a source build)
exact failing step
whether failure is global or app-specific
current permission states
configured insertion method order
screenshot or text of the Test Setup result

Include whether live preview was enabled, the approximate recording duration, and whether the failure affected preview, final text, insertion, or History. Redact private transcripts, nearby editor text, audio, and raw logs before sharing.