Troubleshooting

macOS blocks the app on first launch ("unidentified developer")

liltype is not yet notarized with an Apple Developer certificate. macOS Gatekeeper will show a warning the first time you open the app.

1. Open System Settings → Privacy & Security
2. Scroll down to the security section
3. Click Open Anyway next to the liltype message
4. Confirm in the dialog that appears

You may need to repeat this after updating to a new version.

"Download a model to enable dictation."

Go to Settings → Model and download at least one offline model.

"Local model transcription runtime unavailable in this build."

From project root:

swift build

Then relaunch app.

"API key invalid — check settings."

• Re-enter key in Settings → Model
• Remove accidental spaces/newlines
• Verify provider billing/quota
• Click Test Connection before saving

Microphone doesn't work

• Grant microphone permission in macOS privacy settings
• Confirm correct input device in Settings → System
• Speak and verify level meter activity

Auto-paste doesn't insert text

• Grant Accessibility permission
• Confirm auto-paste is enabled in settings
• Test in a simple app first (Notes/TextEdit)

Text ends up in clipboard but isn't pasted

If the focused app lost focus between dictation start and transcription completion, liltype sends a notification instead of pasting. Re-focus the target app and paste manually (Cmd+V).

Meeting/system audio capture not working

• Ensure screen recording/system audio permission is granted in macOS System Settings
• Confirm monitored app and meeting settings are configured in Settings → Meeting
• Retry with target app relaunched

Meeting session not auto-detected

• Check that the app is in the monitored apps list in Settings → Meeting
• Verify detection behavior is set to "ask" or "auto-start" (not "notify only")
• Ensure the meeting app is running and in the foreground

Speaker labels show "Unknown speaker"

• Speaker diarization is heuristic-based; confidence threshold affects how speakers are separated
• Lower the confidence threshold in Settings → Meeting to label more segments
• You can manually rename speakers in the session view

Agent workspace not receiving transcript

• Confirm an agent session is linked to the meeting recording
• Check that the companion type (Claude / Codex / Gemini / Custom) is correctly selected
• Transcript sync is debounced 500 ms — wait briefly after the session ends

Cloud provider fails after working previously

• Key may have been revoked or quota exceeded — re-enter in Settings → Model
• Check provider status page for outages
• liltype will auto-fall back to offline mode if cloud fails or the daily cost cap is reached

Hotkey not triggering

• Change shortcut in Settings → General
• Avoid known macOS conflicts (Spotlight/input source)
• Test with another key combo

Observability has no data

• Run a few dictation attempts first
• Ensure local debug retention is enabled if required for your metrics view

Clipboard history is empty

• Clipboard history is disabled by default — enable it in Settings → Advanced
• Set a retention policy (1 week / 1 month / 3 months / 1 year / forever)

Sequential paste hotkey does nothing

• Clipboard history must be enabled in Settings → Advanced
• Confirm a sequential paste hotkey is configured and doesn't conflict with other shortcuts
• The sequence timeout may have reset; trigger the hotkey again

Last resort reset path

1. Quit liltype
2. Relaunch
3. Re-run permission setup
4. Re-test in offline mode first
5. Add cloud features only after offline path is stable