Troubleshooting Mibyan Desktop

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

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.

Find your problem

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

Mibyan Cloud agent is down

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.

The installer fails on 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.

A remote display makes the window flicker

When Mibyan detects a remote display, it switches to software rendering to prevent flickering and tells you so with a banner.

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.

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.

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.

Start here

Products

Use Mibyan

Agents

Model and evaluation

Troubleshooting Mibyan Desktop

Find your problem

Startup

”Mibyan couldn’t start”

Connection

Turn errors

Voice problems

Notifications do not appear

Tools and MCP

Preview and terminals

Updates

Send diagnostics to Mibyan

​Find your problem

​Startup

​”Mibyan couldn’t start”

​Connection

​Turn errors

​Voice problems

​Notifications do not appear

​Tools and MCP

​Preview and terminals

​Updates

​Send diagnostics to Mibyan

Find your problem

Startup

”Mibyan couldn’t start”

Connection

Turn errors

Voice problems

Notifications do not appear

Tools and MCP

Preview and terminals

Updates

Send diagnostics to Mibyan