Invalid guest mount path "{}": platform-specific prefixes ar

Error message

Invalid guest mount path "{}": platform-specific prefixes are not supported

What it means

normalized_mount_path rejects guest mount paths that contain a Component::Prefix (platform-specific prefixes such as Windows drive letters 'C:\' or UNC '\\server\share'). Such prefixes have no meaning inside the guest's POSIX-like virtual root, so the mount is refused rather than silently misinterpreted.

Source

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

    }

    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)
}

fn prepare_filesystem(
    base_root: Arc<dyn FileSystem + Send + Sync>,
    memory_limiter: Option<&DynFsMemoryLimiter>,
    mounted_dirs: &[MountedDirectory],
    container_mounts: Option<&BinaryPackageMounts>,
    conflict_behavior: ExistingMountConflictBehavior,
) -> Result<WasiFsRoot, Error> {
    let mut root_layers: Vec<Arc<dyn FileSystem + Send + Sync>> = Vec::new();

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

Use a rooted POSIX-style guest path (start with '/') for the guest side, e.g. '/data' instead of 'C:\\data'
Put the Windows drive/UNC path only in the HOST portion of the mount mapping
If building both sides from one string, split on the mount separator and convert the guest side with Path::new(guest).components() filtering or by hardcoding a rooted virtual path
On Windows hosts, disable path-prefix auto-detection by constructing the guest path explicitly from '/' + components rather than reusing the host PathBuf

Example fix

// before
let guest = PathBuf::from("C:\\data"); // Prefix component
runner.with_mount(guest, host_dir)?;
// after
let guest = PathBuf::from("/data");
runner.with_mount(guest, host_dir)?; // host_dir may be C:\data

Defensive patterns

Strategy: validation

Validate before calling

fn validate_no_prefix(guest: &std::path::Path) -> Result<(), String> {
    use std::path::Component;
    for c in guest.components() {
        if let Component::Prefix(_) = c {
            return Err(format!(
                "guest mount path must be POSIX-style, got: {}",
                guest.display()
            ));
        }
    }
    Ok(())
}
validate_no_prefix(std::path::Path::new("/data"))?;

Type guard

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

Prevention

On Windows hosts, never reuse a host PathBuf for the guest side of a mount; build the guest path from a '/' root explicitly
Keep host (drive-letter/UNC) and guest (POSIX) paths in clearly separated config fields
Test mount configs on a Linux CI job to catch Windows-only prefix paths early
Strip drive letters programmatically if converting host paths into guest paths, then re-root at '/'

When it happens

Trigger: Calling prepare_filesystem with a Windows-style absolute guest path like 'C:\\data', 'D:\\', or a UNC path '\\\\server\\share' as the GUEST side of a mount mapping (typically when running/building on Windows and passing the host path into the guest slot by mistake).

Common situations: Users on Windows copying their host path into both sides of a --mapdir/mount config; config files authored on Windows then used cross-platform; programmatic PathBuf::from("C:\\...") passed as guest path.

Related errors

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