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

# Troubleshooting Mibyan Desktop

> Fixes for startup, connection, credits, voice, notifications, previews, and updates, and how to send diagnostics safely

Start with the message you see. Mibyan Desktop names the layer that failed, so the fix is usually one click.

<Info>
  Nothing on a recovery screen deletes your chats or settings. When you are unsure, **Open logs** first. It reveals the desktop log in your file manager.
</Info>

## Find your problem

```mermaid theme={null}
flowchart TD
  A["Something is wrong"] --> B{"Where?"}
  B -- "App will not start" --> S["Startup"]
  B -- "Cannot reach the agent" --> C["Connection"]
  B -- "A turn failed" --> T["Turn errors"]
  B -- "Voice" --> V["Voice"]
  B -- "Preview or terminal" --> P["Preview"]
  B -- "Update" --> U["Updates"]
```

## Startup

### "Mibyan couldn't start"

The background gateway did not come up. Try these in order:

| Button | What it does |
| - | - |
| **Retry** | Starts the backend again |
| **Repair install** | Re-runs the installer. It can take a few minutes on a fresh machine |
| **Use local gateway** | Switches from a remote gateway to the bundled local one |
| **Gateway settings** | Check the URL and sign-in |
| **Open logs** and **Show recent logs** | See what failed |
| **Back** | Return to the previous screen |

<AccordionGroup>
  <Accordion title="Remote gateway sign-in required" icon="right-to-bracket">
    Your remote gateway session expired. **Sign out and sign in** clears the saved browser session and opens the sign-in window. **Use local gateway** switches to the bundled backend instead. If the login window closes before it finishes, you see **Sign-in incomplete**. Try again.
  </Accordion>

  <Accordion title="Mibyan Cloud agent is down" icon="cloud">
    The hosted agent your gateway connects to is returning a server error, and it cannot be restarted from the app. Use **Check Portal status** to see its state and controls, **Use local gateway** to keep working, or get help through the support links.
  </Accordion>

  <Accordion title="The installer fails on Windows" icon="windows">
    Another Mibyan command line or desktop instance may be running. Stop them and retry. If your antivirus quarantines `uv.exe` from the Mibyan `bin` folder, that is a **false positive**: it is the package manager Mibyan uses for its Python environment. Add the **folder** (not the file) to your antivirus exclusions, because the file changes with each version.
  </Accordion>

  <Accordion title="A remote display makes the window flicker" icon="display">
    When Mibyan detects a remote display, it switches to software rendering to prevent flickering and tells you so with a banner.
  </Accordion>
</AccordionGroup>

## Connection

| You see | What it means | Do this |
| - | - | - |
| **Lost connection to the gateway** | The link dropped. The app keeps retrying in the background, and you can still read and draft | Wait, or open **Gateway settings** if it persists. Use **Reconnect gateway** from the status bar menu |
| **Gateway sign-in required** | The saved sign-in is no longer valid | Sign in again in **Settings, Gateways** |
| **Gateway authentication failed** | The key the gateway expects does not match | Check the gateway's API server key |
| **405 Method Not Allowed** | The desktop backend rejected a request | Restart Mibyan Desktop |
| **Couldn't load this session** | The connection to the session failed and automatic retries gave up | Check that the gateway is running, then **Retry** |
| A messaging platform shows **Restart needed** | A change needs the gateway restarted | Restart the gateway from the status bar |
| **Messaging gateway stopped** | The messaging gateway is not running | Start it from the status bar, or run `mibyan gateway` |
| Handoff times out | The messaging gateway did not answer | Check that `mibyan gateway` is running |

A connection test can pass while the live connection fails. The app's test exercises the same sign-in and WebSocket path the app really uses, so if the test passes, the setup is right.

## Turn errors

A failed turn names its layer, so you know where to look:

| Layer | Typical cause | Action |
| - | - | - |
| **Authentication error** | A key or sign-in was rejected | Re-enter the key, or **Reconnect Mibyan account** |
| **Out of credits** | Your account has no credits | **Open billing** or **Add credits**, or use your own provider |
| **Disk full** | No space to write | Free space, then try again |
| **Custom endpoint error** | Your OpenAI-compatible server failed | Check the server and its URL |
| **Gateway error** | The backend had a problem | **Open logs** |
| **Provider error** | The model provider rejected the call | **Switch provider** |
| **Local runtime error** | The local backend hit a problem | **Retry**, then **Repair install** |
| **Streaming connection error** | The stream broke mid-answer | **Retry** |

Every error offers **Copy error details** and **Send diagnostics**.

## Voice problems

| You see | Fix |
| - | - |
| Configure speech-to-text to use voice mode | Turn on **Speech to text** and choose a provider in **Settings, Voice** |
| Microphone permission was denied | Allow the microphone for Mibyan in your system privacy settings |
| Microphone is already in use by another app | Close the other app |
| No microphone was found | Connect one, or pick another input in your system settings |
| No speech detected | Speak closer to the microphone and try recording again |
| A provider rejected the key, or a key is missing | Add the key that provider needs in **Settings, Tools and Keys**. For example ElevenLabs speech-to-text needs `ELEVENLABS_API_KEY`, and OpenAI text-to-speech needs `VOICE_TOOLS_OPENAI_KEY` or `OPENAI_API_KEY` |
| Voice transcription is not available yet | The transcription service is not ready. Check the provider settings |

## Notifications do not appear

Use **Settings, Notifications, Send test notification**. If nothing shows, check your system's notification permission for Mibyan and Focus or Do Not Disturb. Remember that completion alerts only fire while Mibyan is in the background, and the master **Enable notifications** switch must be on.

## Tools and MCP

* **MCP server needs re-authentication:** open it in **Capabilities, MCP** and choose **Authenticate**.
* **MCP server unreachable:** it failed its health check. Use **Test connection**, then **Reload MCP**.
* A tool call fails with a connection error: use the **Reconnect** chip that appears in the composer.
* A tool is missing: changes apply to **new sessions**, so start a new chat.

## Preview and terminals

| Problem | Fix |
| - | - |
| "Server not found" or the preview will not load | **Ask Mibyan to restart the server**, and watch the preview console |
| The address points at the agent's machine | On a remote backend, a `localhost` address is not reachable from your computer. Use a port forward or a reachable hostname |
| Module scripts served with the wrong type | A static file server is serving a Vite or React app instead of the project dev server. Ask Mibyan to start the dev server |
| A file is huge or binary | Only the first 512 KB is shown. Choose **Preview anyway**, or attach it as context |
| Terminal icons look wrong | Choose a Nerd Font in **Settings, Appearance, Terminal font** |

## Updates

| You see | Fix |
| - | - |
| **Update paused** or **Update didn't finish** | Nothing was lost. Try again |
| **Close local previews to update** | Choose **Close previews and update**. Files are not touched |
| **Close other processes to update** | Close the app, terminal, or service that owns each listed process |
| **Backend out of date** | Choose **Update Mibyan** |
| **App build out of date** or **Update the desktop app** | Update or reinstall the desktop app from the latest installer |
| The backend did not come back after an update | Check the backend host |

See [Install and update](/products/desktop-guide/install-and-update).

## Send diagnostics to Mibyan

When you need help, **Send diagnostics** uploads a debug bundle privately so support can see your logs. The dialog shows what it includes **before** you upload.

* **It includes:** system information (OS, versions, provider, and which API keys are configured, never the keys themselves) and the agent, gateway, and desktop logs, up to 512 KB each.
* **It may contain:** conversation content, tool outputs, and file paths, because logs can include them. Secrets are redacted before upload.
* **Who can see it:** only Mibyan staff and allowlisted support moderators. It is not a public paste, and it auto-deletes after **14 days**.

You can also run `mibyan debug share` from a terminal, or `mibyan debug share --local` to print the report **without uploading**. The Command Center **Debug share** action uploads a redacted report whose links auto-delete after **6 hours**.

After uploading, copy the link into your support thread. The dialog links to **Mibyan Support**, **Discord**, and **GitHub Issues** so you can continue the conversation. If a view link is not returned, quote the upload ID to support.

<Warning>
  Read the privacy notice in the dialog before uploading. If your logs may contain private content, use `mibyan debug share --local` and review the report first.
</Warning>