Desktop App Troubleshooting
This page covers the desktop app. For the engine, see Wayland Core Troubleshooting. Each entry is a problem, its likely cause, and the fix.
The app will not launch
Section titled “The app will not launch”Problem: the window never appears, or it opens and closes.
Cause: a corrupt install, an OS quarantine flag on a fresh download, or a stale local state directory.
Fix:
- On macOS, if the app is blocked as unverified, open it once from the right-click menu to clear the quarantine flag, then launch normally.
- Reinstall from a fresh download rather than updating in place. See Install the Desktop App.
- If it still fails, the issue may be local state. Back up first, then try the reset described at the end of this page.
The engine binary is not found
Section titled “The engine binary is not found”Problem: chat does nothing, and the app reports that Wayland Core is unavailable.
Cause: the desktop app bundles and prepares a matching wayland-core binary on first run. If that preparation did not finish, or the bundled binary for your platform is missing, the engine cannot start.
Fix:
- Restart the app so first-run preparation can complete.
- Open the Wayland Core status panel in settings and check the reported version and binary path. If the path is empty or the version is blank, the binary was not prepared.
- Reinstall the app to restore the bundled binary. The desktop and engine ship together and share config, so a clean reinstall realigns them.
The dashboard is blank or assistants are missing
Section titled “The dashboard is blank or assistants are missing”Problem: the dashboard loads but the assistant library is empty, or extension-bundled assistants do not appear.
Cause: extension-bundled assistants resolve as the app loads. A brief flash before they resolve is normal on a cold start. A persistently empty library points to a load that did not finish.
Fix:
- Wait a few seconds on first open, then reload. The library should populate with all built-in and extension-bundled assistants once the extension resolves.
- If it stays empty, restart the app. A failed cold load usually clears on the next launch.
- Confirm a model provider is connected. Without one, the dashboard renders but cannot do work. See Connect Your First Model.
Login loops
Section titled “Login loops”Problem: you sign in, but the app returns to the login screen.
Cause: a stale or partial credential, or an interrupted OAuth round trip.
Fix:
- Sign out fully, then sign in again so a fresh credential is written.
- For Anthropic OAuth, completing the flow in the browser and returning to the app should land you on the dashboard. If the loop persists, an API key is a reliable fallback. See Provider and Auth Errors.
Reset everything
Section titled “Reset everything”Problem: the app is in a bad state no single fix clears.
Cause: accumulated local state that needs to be cleared.
Fix: the storage settings panel has a danger-zone reset that wipes local app data. It asks you to type a confirmation word before it proceeds, because it is destructive. Back up first if you have conversations or memory you want to keep, then reset and set up the app again from a clean state. See Back Up and Sync before you do this.