---
id: troubleshooting
title: Troubleshoot Bex Desktop
description: Diagnose unavailable downloads, launch and graphics failures, shared Zed profiles, unsaved files, and update problems in Bex Desktop.
sidebar_position: 3
last_updated: 2026-09-23
---

Start with the symptom below. These cases are grounded in [bex-v1.20.0-bex.4](https://github.com/bex-co/bex-desktop/releases/tag/bex-v1.20.0-bex.4), its packaging, or the verified [local-file walkthrough](quickstart.md). Keep your project files and profile when investigating a failure.

## No download button for my platform

[/download](/download) enables only OS/architecture assets found in validated release metadata. An unavailable release service means the page could not load the release. A release with no installers means the lookup succeeded but no supported desktop assets were found. Neither state proves that your computer is unsupported.

Follow the page's GitHub releases link and check the asset list. Choose the correct architecture using the [installation guide](installation.md). Do not use a remote-server archive as the desktop app. The recovery result is a matching desktop installer from the Bex repository, with a digest matching that release's `SHA256SUMS`.

## macOS says another editor is already running

The pinned build can print `zed is already running` even when you launched Bex with a separate `--user-data-dir`. This was reproduced during validation: Bex and Zed share the stable-channel single-instance check on macOS.

Save your work in the other editor and quit it normally, then launch Bex again. Do not force-quit a process with unsaved work. A separate [profile](installation.md) keeps settings/data separate, but does not change this instance check. The expected recovery is a Bex window showing your selected local project.

## The app cannot launch, or the window is blank

First verify the download source, architecture, and checksum. On macOS, the signed artifact must pass the operating system's normal checks. If the system rejects it, download a fresh copy of the same release and report the exact warning; this guide does not prescribe disabling Gatekeeper or removing quarantine attributes.

On Windows, check the [source-derived OS and graphics prerequisites](installation.md) and install the current graphics driver from your hardware vendor. On Linux, errors naming a missing `GLIBC` version or `NoSupportedDeviceFound` point to the runtime or Vulkan requirements described in [Linux installation](installation.md). Test graphics in a real desktop session; an SSH shell or minimal container alone cannot establish GUI support.

For Linux graphics diagnosis, `vulkaninfo --summary` can confirm the installed Vulkan driver, if your distribution's Vulkan tools are installed. Upgrade an unsupported system or driver rather than replacing individual system libraries from an unrelated distribution. Recovery means the editor opens a window and can complete the plain-text walkthrough.

## My edit did not reach the file

Use **File → Save**, then reopen the file and compare it with the file manager's copy. Confirm you opened the intended folder and have write permission there. A new file created in an editor tab needs a destination before it exists on disk.

Try the [two-line example in a new folder](quickstart.md). If it succeeds, compare the original folder's permissions and path. Do not delete a project or reset the profile to diagnose a save failure.

## Update checks fail or the version looks unchanged

Open [/download](/download) and the linked release page to distinguish a feed problem from a missing new release. The pinned app's update implementation uses Bex's server URL and preserves Bex revision comparisons. It does not treat an upstream Zed release as a newer Bex build.

Save your files before restarting to apply an update. If the automatic path fails, use the [manual update procedure](installation.md). On macOS, the bundled launcher's version output reports the base version and app path; compare the bundle revision and pinned release as well. A full upgrade cycle was not validated for this guide.

## Collect a useful report

Include the release tag, OS version, architecture, exact error, and the smallest reproducible steps in the [Bex Desktop issue tracker](https://github.com/bex-co/bex-desktop/issues). The source provides a **zed: open log** command in the command palette. The name is inherited even when the app is branded Bex.

The pinned macOS log path remains `~/Library/Logs/Zed/Zed.log`, including when a custom data directory is used. Linux and Windows logs live under the data directory's `logs` subdirectory. Inspect logs before sharing them and include only the lines needed to demonstrate the failure. Return to [installation](installation.md) or the [first-session guide](quickstart.md) after resolving it.