Invalid guest mount path "{}": parent traversal escapes the

Error message

Invalid guest mount path "{}": parent traversal escapes the virtual root

What it means

normalized_mount_path canonicalizes a guest mount path before wiring it into the WASI filesystem. When a '..' component would pop past the root of the virtual filesystem (i.e. the normalized path is already '/' and another ParentDir is seen), it refuses the mount because the path escapes the virtual root, which would be unsafe/ambiguous.

Source

Thrown at lib/wasix/src/runners/wasi_common.rs:206

    vars.into_iter()
        .map(|(name, value)| (name.into_encoded_bytes(), value.into_encoded_bytes()))
}

fn normalized_mount_path(guest_path: &str) -> Result<PathBuf, Error> {
    let mut guest_path = PathBuf::from(guest_path);

    if guest_path.is_relative() {
        guest_path = apply_relative_path_mounting_hack(&guest_path);
    }

    let mut normalized = PathBuf::from("/");
    for component in guest_path.components() {
        match component {
            Component::RootDir => normalized = PathBuf::from("/"),
            Component::CurDir => {}
            Component::ParentDir => {
                if normalized.as_os_str() == "/" {
                    anyhow::bail!(
                        "Invalid guest mount path \"{}\": parent traversal escapes the virtual root",
                        guest_path.display()
                    );
                }
                normalized.pop();
            }
            Component::Normal(part) => normalized.push(part),
            Component::Prefix(_) => {
                anyhow::bail!(
                    "Invalid guest mount path \"{}\": platform-specific prefixes are not supported",
                    guest_path.display()
                );
            }
        }
    }

    Ok(normalized)
}

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

Remove the leading/extra '..' components from the guest side of the mount spec so it stays within the virtual root
If you intended to mount a host parent directory, move the '..' to the HOST path portion of the mount mapping, keeping the guest path absolute and rooted (e.g. guest '/data' -> host '../data')
Normalize the path yourself before passing it in (e.g. path.clean() semantics) and assert it stays under '/'
If the input comes from user config, validate/reject it at config-load time with a clearer message

Example fix

// before
runner.with_mount("..", "/guest/data")?;
// after: keep the '..' on the host side, guest path rooted
runner.with_mount("/guest/data", "../host-data")?;

Defensive patterns

Strategy: validation

Validate before calling

fn validate_guest_mount_path(guest: &str) -> Result<(), String> {
    use path_clean::PathClean;
    let p = std::path::Path::new(guest);
    if !guest.starts_with('/') {
        return Err(format!("guest mount path must be absolute: {guest}"));
    }
    let cleaned = p.clean(); // resolves '..' lexically
    if cleaned.components().any(|c| matches!(c, std::path::Component::ParentDir)) {
        return Err(format!("guest mount path escapes virtual root: {guest}"));
    }
    Ok(())
}
validate_guest_mount_path("/data")?;

Type guard

fn is_rooted_guest_path(p: &std::path::Path) -> bool {
    use std::path::Component;
    p.is_absolute()
        && p.components()
            .all(|c| !matches!(c, Component::ParentDir | Component::Prefix(_)))
}

Prevention

Always author guest mount paths as absolute, rooted paths ('/x/y') in config
Never pass user-controlled paths directly into the guest slot without normalization
Keep '..' moves on the host side of the mapping only
Add a config-load-time lint that rejects non-canonical guest paths with a clear message

When it happens

Trigger: Calling prepare_filesystem (or the runner setup) with a guest mount path containing leading or excess '..' components, e.g. '..' , '/../data', '/a/../..' — any path whose normalization underflows root.

Common situations: Configuration mistakes in mount maps (e.g. TOML/CLI --mapdir with '..' in the guest side); programmatically-built paths joined with user input containing '..'; Windows-style habits where relative parent paths were expected to resolve against a host cwd.

Related errors

AI-assisted analysis of wasmerio/wasmer@8c4b9ee9d3 (2026-09-01). Data as JSON: /api/errors/c3ba11422d1dad24. Report an issue: GitHub.