zed-industries/zed · error · anyhow::Error

ZED_WSL_SANDBOX_HELPER is not valid UTF-8

Error message

ZED_WSL_SANDBOX_HELPER is not valid UTF-8

What it means

Raised in ensure_wsl_zed_helper when the ZED_WSL_SANDBOX_HELPER environment variable (used to override the helper path) contains non-UTF-8 bytes, so it cannot be treated as a path. The override is rejected and helper provisioning does not proceed.

Source

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

/// inside WSL and return its absolute in-WSL path, to be `--exec`'d as the
/// `--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()

View on GitHub (pinned to f4178619ac)

Solutions

1. Set ZED_WSL_SANDBOX_HELPER to a valid UTF-8 path or unset it

When it happens

Trigger: Thrown at crates/sandbox/src/windows_wsl.rs:868 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/127244f1488f1cbd. Report an issue: GitHub.