zed-industries/zed · error

ZED_WSL_SANDBOX_HELPER must be an absolute path inside WSL

Error message

ZED_WSL_SANDBOX_HELPER must be an absolute path inside WSL

What it means

Validation in ensure_wsl_zed_helper(): the ZED_WSL_SANDBOX_HELPER value is not an absolute path inside WSL, which is required because it is passed as the --wsl-sandbox-helper argument to commands run in WSL.

Source

Thrown at crates/sandbox/src/windows_wsl.rs:869

/// `--wsl-sandbox-helper`. Runs [`HELPER_PROVISION_SCRIPT`] (which downloads the
/// matching release tarball into an off-`PATH` location on first use).
///
/// Successful resolutions are cached per `(distro, channel, version)` for the
/// life of the process — once provisioned, the path won't change. Failures are
/// not cached, so a user who installs `curl` (or fixes networking) after an
/// error can retry without restarting Zed.
async fn ensure_wsl_zed_helper(
    wsl_exe: &Path,
    distro: Option<&str>,
    channel: &str,
    version: &str,
) -> Result<String> {
    // TODO: Remove this development override once WSL canonical-path handling is released.
    if let Some(helper) = std::env::var_os("ZED_WSL_SANDBOX_HELPER") {
        let helper = helper
            .into_string()
            .map_err(|_| anyhow::anyhow!("ZED_WSL_SANDBOX_HELPER is not valid UTF-8"))?;
        ensure!(
            helper.starts_with('/'),
            "ZED_WSL_SANDBOX_HELPER must be an absolute path inside WSL"
        );
        return Ok(helper);
    }

    type HelperCache = HashMap<(Option<String>, String, String), String>;
    static CACHE: OnceLock<Mutex<HelperCache>> = OnceLock::new();
    let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));

    let key = (
        distro.map(str::to_string),
        channel.to_string(),
        version.to_string(),
    );
    if let Some(path) = cache
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner())

View on GitHub (pinned to f4178619ac)

Solutions

1. Set ZED_WSL_SANDBOX_HELPER to an absolute Linux path (e.g. /usr/local/lib/zed/...)
2. Unset the variable to let Zed auto-provision the helper at its standard absolute location

When it happens

Trigger: Thrown at crates/sandbox/src/windows_wsl.rs:869 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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