zed-industries/zed · error

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

Thrown by the Docker remote transport when Zed runs in the dev release channel, the container does not already contain a zed-remote-server binary at the expected path, and ZED_BUILD_REMOTE_SERVER is not set. Dev builds have no downloadable prebuilt server (nightly skips version checks, stable/preview resolve an AppVersion to download), so a locally built server must be supplied via that environment variable.

Source

Thrown at crates/remote/src/transport/docker.rs:280

                &tmp_path,
                &remote_dir_for_server,
                delegate,
                cx,
            )
            .await?;
            self.extract_server_binary(&dst_path, &tmp_path, &remote_dir_for_server, 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_gz = paths::remote_server_dir_relative().join(
            RelPath::from_unix_str(&format!(
                "{}-download-{}.gz",
                binary_name,
                std::process::id()
            ))
            .unwrap(),
        );
        if !self.connection_options.upload_binary_over_docker_exec
            && let Some(url) = delegate
                .get_download_url(remote_platform, release_channel, wanted_version.clone(), cx)

View on GitHub (pinned to 5a9b9558db)

Solutions

1. Build the remote server in the Zed repo (script/remote-build) and export ZED_BUILD_REMOTE_SERVER to the produced target/remote/release/zed-remote-server-<target>.gz, then relaunch Zed from that shell
2. Pre-place the server binary in the container at the dst_path shown in the error so binary_exists_on_server passes and no env var is needed
3. Run a release, preview, or nightly build of Zed instead of the dev build so the prebuilt server is downloaded
4. Verify the variable reaches the process: launch Zed from the same terminal after exporting, or check with `ps eww <pid>`

Example fix

# before
./target/debug/zed   # dev channel, ZED_BUILD_REMOTE_SERVER unset

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

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

match connection.launch_server(cx).await {
    Err(e) if e.to_string().contains("ZED_BUILD_REMOTE_SERVER") => {
        // dev channel: instruct user to build + set env var, then retry once
    }
    result => result,
}

When it happens

Trigger: Connecting the Docker transport from a locally compiled (ReleaseChannel::Dev) Zed: the binary_exists_on_server check fails and the release-channel match hits the Dev arm with ZED_BUILD_REMOTE_SERVER absent from the Zed process environment.

Common situations: Zed contributors testing remote development against a container; ZED_BUILD_REMOTE_SERVER exported in a different shell than the one that launched Zed; Zed started from a GUI launcher/dock that does not inherit the terminal environment; CI runs using dev builds.

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

• ZED_BUILD_REMOTE_SERVER is not set and no remote server exis
• failed to upload via docker cp {} -> {}: {}
• failed to change ownership for zed_remote_server via chown:
• Neither curl nor wget is available
• Remote server exited with status {status}

AI-assisted analysis of zed-industries/zed@5a9b9558db (2026-08-20). Data as JSON: /api/errors/302ef36e6bc08113. Report an issue: GitHub.