ZED_BUILD_REMOTE_SERVER is not set and no remote server exis

Error message

ZED_BUILD_REMOTE_SERVER is not set and no remote server exists at ({:?})

What it means

SSH-transport equivalent of the dev-channel provisioning guard: when ReleaseChannel::Dev, no server binary already exists on the remote host, and ZED_BUILD_REMOTE_SERVER is unset, Zed cannot obtain a remote server (dev builds are not published for download) and bails, embedding the expected destination path.

Source

Thrown at crates/remote/src/transport/ssh.rs:897

                    remote_server_path.file_name().unwrap().to_string_lossy()
                ))
                .unwrap(),
            );
            self.upload_local_server_binary(&remote_server_path, &tmp_path, delegate, cx)
                .await?;
            self.extract_server_binary(&dst_path, &tmp_path, delegate, cx)
                .await?;
            return Ok(dst_path.into());
        }

        if binary_exists_on_server {
            return Ok(dst_path.into());
        }

        let wanted_version = cx.update(|cx| match release_channel {
            ReleaseChannel::Nightly => Ok(None),
            ReleaseChannel::Dev => {
                anyhow::bail!(
                    "ZED_BUILD_REMOTE_SERVER is not set and no remote server exists at ({:?})",
                    dst_path
                )
            }
            _ => Ok(Some(AppVersion::global(cx))),
        })?;

        let tmp_path_compressed = remote_server_dir_relative().join(
            RelPath::from_unix_str(&format!(
                "{}-download-{}.{}",
                binary_name,
                std::process::id(),
                if self.ssh_platform.os.is_windows() {
                    "zip"
                } else {
                    "gz"
                }
            ))

View on GitHub (pinned to f4178619ac)

Solutions

Build the server (script/remote-build in the Zed repo) and export ZED_BUILD_REMOTE_SERVER to the built .gz artifact, then relaunch Zed in that shell
Upload the server binary manually to the dst_path named in the error so the existing-binary check passes
Use a stable/preview/nightly Zed build, which downloads a versioned prebuilt server instead
Confirm the variable actually reaches the Zed process environment before connecting

Example fix

# before
./target/debug/zed  # dev channel, no env var set

# after
script/remote-build
export ZED_BUILD_REMOTE_SERVER="$PWD/target/remote/release/zed-remote-server-linux-x86_64.gz"
./target/debug/zed

Defensive patterns

Strategy: validation

Validate before calling

fn ssh_dev_server_provisionable(release_channel: ReleaseChannel) -> bool {
    match release_channel {
        ReleaseChannel::Dev => std::env::var("ZED_BUILD_REMOTE_SERVER").is_ok(),
        _ => true,
    }
}

Try / catch

match ssh_connection.launch_server(cx).await {
    Err(e) if e.to_string().contains("ZED_BUILD_REMOTE_SERVER") => {
        // dev build: build the server, set the env var, relaunch, then retry
    }
    result => result,
}

Prevention

Run script/remote-build and export ZED_BUILD_REMOTE_SERVER in the launching shell
Start dev builds of Zed from a terminal, not a desktop launcher
Assert the env var in dev/test scripts before opening SSH remotes

When it happens

Trigger: Connecting over SSH from a locally compiled Zed: binary_exists_on_server is false and the release-channel match enters the Dev arm with ZED_BUILD_REMOTE_SERVER missing from the environment.

Common situations: Contributors testing SSH remote dev with a dev build; env var exported in a shell other than the one launching Zed; launching Zed from a desktop launcher that drops terminal environment; fresh checkouts that never ran the remote build script.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of zed-industries/zed@f4178619ac (2026-08-20). Data as JSON: /api/errors/9da712b3ec448e8c. Report an issue: GitHub.