Troubleshooting

This page covers the issues that most often block a first session from completing. If you hit something not listed here, email support@vathus.ai with the text of the banner you are seeing.

macOS microphone permission denied

Symptom. The Practice readiness banner says microphone permission is not granted; Start session is disabled.

Fix.

1. Open System Settings → Privacy & Security → Microphone.
2. Find Mockingbird in the list and toggle it on. If Mockingbird is not in the list, the first session attempt has not yet reached the TCC prompt: start a session, approve the prompt, and it will appear.
3. Restart Mockingbird. macOS caches TCC decisions per-app-launch, so the app must relaunch to observe the new grant.

The 'unknown' permission state specifically does not count as OK inside Electron. If the banner is stuck on unknown, the TCC database has never seen the app: re-installing or moving the .app to /Applications and re-launching usually clears it.

macOS Screen Recording permission

Symptom. You enabled Settings → General → System audio capture but no system-side audio is reaching the transcript.

Fix.

1. Open System Settings → Privacy & Security → Screen & System Audio Recording.
2. Toggle Mockingbird on.
3. Restart Mockingbird. As with microphone, the TCC cache requires a relaunch.

System-audio capture uses Electron's desktopCapturer → getUserMedia({ audio: { mandatory: { chromeMediaSource: 'desktop' } } }). Without Screen Recording permission the call returns no audio track, which is why you see no transcript for the second speaker.

Deepgram connection fails

Symptom. Real-session banner reports a Deepgram error; the WebSocket closes immediately after opening.

Common causes.

• Invalid BYOK key. If you are on BYOK, re-paste the key into Account → API keys. A stored key shows as "key stored" with no content. If that badge is missing, the save failed.
• Vathus token issue. If you are on Pro, retry once. The desktop app asks Vathus for a fresh short-lived token at session start; repeated failures usually mean the Vathus backend is missing DEEPGRAM_API_KEY or your account session expired.
• No credit on the account. The Deepgram free tier has a $200 cap. Once exhausted, the Nova streaming endpoint rejects new connections. Log in to the Deepgram console and add billing or top up credit.
• Firewall blocking wss://api.deepgram.com. Corporate networks sometimes block WebSockets to non-allowlisted origins. Test on another network to isolate.
• System time drift. Deepgram signs the upgrade request with a timestamp-sensitive bearer token. If your machine clock is more than a few minutes off UTC, the upgrade is rejected.

The error banner surfaces the provider's real response, no more generic "Unavailable in this build" messages. Read what it says before assuming it is our bug.

Parakeet runtime unavailable

Symptom. Models page shows "PARAKEET_RUNTIME_UNAVAILABLE" at the top of the speech section and no Parakeet rows are downloadable.

Cause. The native sherpa-onnx binary failed to load. We publish prebuilt binaries for macOS (x64 + arm64), Windows (x64), and Linux (x64). On other platforms the dynamic import of sherpa-onnx-node throws.

Workaround. Use Online Mode on Pro while we track Linux ARM support. BYOK still uses local transcription by default, so it depends on the same local runtime.

Ollama not detected

Symptom. The Models page says "No local LLM runtime detected" even though you have ollama serve running.

Fix.

1. Confirm Ollama is actually listening on http://127.0.0.1:11434. In a terminal:

   curl http://127.0.0.1:11434/api/tags
   

   You should get a JSON response listing pulled models. If this fails, Ollama is not running: start it with ollama serve or launch the Ollama app.

2. If that works but Mockingbird still does not see it, the main-process health check has cached a failure. Restart Mockingbird: the router re-probes on boot.

3. Pull the local model from the Models page with one click, or from the CLI with ollama pull gemma4:31b. Once Gemma 4 31B is present, trial and starter tiers prefer it for privacy-sensitive tasks (practice scoring and rewrites).

Overlay will not hide

Symptom. The overlay is stuck visible; ⌘⇧\ does nothing.

Fix. Global shortcuts require that no other app has grabbed the same combination. If you installed a window manager that binds ⌘⇧\, it will consume the event before Mockingbird sees it. Either release the binding in the other app, or rebind Mockingbird's shortcut in src/shared/constants.ts → GLOBAL_HOTKEYS for now (a UI-driven rebind is tracked but not yet shipped).

If the overlay is visible but unresponsive to clicks, check Settings → Overlay → Focusable. If you deliberately set focusable off, click-through is enabled by design; toggle it back on to interact.

Panic did not delete turns

Symptom. You pressed ⌘⇧X, the overlay hid, but reviewing the session on the Sessions page still shows content from the last 60 seconds.

Causes to check.

• The hotkey was grabbed by another app. Same as overlay hide: another global-shortcut consumer may be swallowing the event. Test by pressing the key and watching if the overlay hides; if it does not, the handler never fired.
• The session had not written to SQLite yet. The panic DELETE runs over the session's row store. If the turn was still in-flight in the orchestrator's in-memory buffer, it would not have been in the store to delete. Subsequent panic presses will clear newer writes.

Auto-update fails

Symptom. On-boot the status bar briefly shows system_update_error.

This is silent outside dev mode, not disruptive, but if you want to investigate, look in the app log (<userData>/logs/) for the electron-updater trace. The most common cause is a GitHub Releases publishing blip during rollout. The app will re-check on the next boot.

Still stuck?

Email support@vathus.ai with:

• The exact banner text (screenshot is fine).
• Your OS + version (e.g. "macOS 14.5").
• Mockingbird version (About dialog shows it).
• What you were doing when it happened.

We respond within a business day.