Start with the symptom below. These cases are grounded in bex-v1.20.0-bex.4, its packaging, or the verified local-file walkthrough. Keep your project files and profile when investigating a failure.
No download button for my platform
/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. 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 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 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. 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. 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 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. 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. 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 or the first-session guide after resolving it.