> ## Documentation Index
> Fetch the complete documentation index at: https://miniti.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# troubleshooting

> common issues and fixes

## i can't start recording / no transcript appears

* check microphone permission in **system settings → privacy & security → microphone**
* on macos, if using system audio, also check **system audio recording** permission
* in byok mode, confirm your deepgram and openai keys are set in **settings → api keys**
* in managed mode, check for an error message on the home / recording screen (service availability or connection issue)

## macos system audio is missing

* make sure **capture system audio** is enabled in settings
* confirm macos system audio permission is granted
* try stopping and starting the session after granting permission

## product names / acronyms are wrong in the transcript

* add them to the [personal dictionary](/docs/features/transcription#personal-dictionary) in settings
* when the meeting is linked to google calendar, the event title and attendee names also help recognition - see [google calendar](/docs/integrations/google-calendar)

## you and remote speakers overlap / labels look mixed on macos

* keep both **microphone** and **system audio** on so each stays on its own transcription channel
* headphones reduce acoustic loopback (your voice bleeding into the system channel)

## bluetooth headphones / audio devices changed and audio looks wrong

bluetooth devices (especially airpods) switch between two modes mid-call: **a2dp** for high-quality playback and **hands-free (hfp/sco)** when the mic is also in use. macos renegotiates sample rates, channel counts, and sometimes the default output device when this happens, which can cause the system-audio tap to briefly stop producing samples. v1.24.1 tightened the recovery path so the capture graph restarts automatically on more of these transitions.

* the app auto-recovers after route / profile changes (for example airpods switching call modes, plugging in wired headphones, unplugging a usb interface, or airplay starting)
* allow up to \~20 seconds for automatic system-audio recovery after a device switch - the app has to detect the route change, tear down the previous tap, and reattach to the new default device
* if audio still looks stuck after that window, stop / resume the session or start a fresh session (`⌘N`) - the transcript you've captured so far is preserved
* microphone capture usually recovers faster than system audio because it's attached to a specific input, not the system default
* for deeper diagnosis, open the [debug log](/docs/reference/debug-log) - route-change events and capture restarts are logged under `app`

## managed mode says limit reached / recording is blocked

* free tier has a 500-minute monthly cap; pro has 5,000 minutes
* upgrade to pro, switch to [byok](/docs/pricing/byok) for unlimited usage, or wait for the monthly reset

## attio issues

* **"send to attio" is missing** - enable it in settings → integrations
* **can't search** - connect your attio account first, then enter at least 2 characters
* **attio backend endpoints are not deployed yet** - your backend deployment does not include attio routes yet
* **0 tasks created** - the meeting may not contain usable action items, or attio may accept the note but not create tasks from the parsed items

## webhooks aren't arriving

* confirm the webhook url is correct in settings
* check your receiver accepts `POST` with `application/json` and responds within 10 seconds with a 2xx
* remember: no retries. if your endpoint is down, the delivery is lost.
* check the [debug log](/docs/reference/debug-log) - webhook success / failure is logged under `app`

## still stuck?

use the [support form](https://miniti.app/support).