wasmerio/wasmer · error

Invalid --map-command flag - host path cannot be empty: '{it

Error message

Invalid --map-command flag - host path cannot be empty: '{item}'

What it means

The counterpart to the alias check in build_mapped_commands: after parsing ALIAS=HOST_PATH and trimming, if the host path side (after '=') is empty the mapping cannot resolve to any host command, so it is rejected. The raw item is included in the message for debugging.

Source

Thrown at lib/cli/src/commands/run/wasi.rs:559

    pub fn build_mapped_commands(&self) -> Result<Vec<MappedCommand>, anyhow::Error> {
        self.map_commands
            .iter()
            .map(|item| {
                let (a, b) = item.split_once('=').with_context(|| {
                    format!(
                        "Invalid --map-command flag: expected <ALIAS>=<HOST_PATH>, got '{item}'"
                    )
                })?;

                let a = a.trim();
                let b = b.trim();

                if a.is_empty() {
                    bail!("Invalid --map-command flag - alias cannot be empty: '{item}'");
                }
                // TODO(theduke): check if host command exists, and canonicalize PathBuf.
                if b.is_empty() {
                    bail!("Invalid --map-command flag - host path cannot be empty: '{item}'");
                }

                Ok(MappedCommand {
                    alias: a.to_string(),
                    target: b.to_string(),
                })
            })
            .collect::<Result<Vec<_>, anyhow::Error>>()
    }

    pub fn capabilities(&self) -> Capabilities {
        let mut caps = Capabilities::default();

        if self.http_client {
            caps.http_client = wasmer_wasix::http::HttpClientCapabilityV1::new_allow_all();
        }

        if let Some(enable_async_threads) = self.enable_async_threads {

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

1. Provide a non-empty host path after the '=', e.g. --map-command ls=/bin/ls
2. Check shell variables used to build the flag are set and non-empty (${CMD:?} guards)
3. Verify the host binary path exists (it is not canonicalized yet per the TODO)

Example fix

// before
CMD=  # unset
wasmer run app.wasm --map-command ls=$CMD
// after
wasmer run app.wasm --map-command ls=/bin/ls

fn validate_map_command_host(item: &str) -> Result<(), String> {
    let (a, b) = item.split_once('=')
        .ok_or_else(|| format!("--map-command must be ALIAS=HOST_PATH, got {item:?}"))?;
    if b.trim().is_empty() { Err(format!("empty host path in {item:?}")) } else { Ok(()) }
}

fn has_nonempty_host_path(item: &str) -> bool {
    item.split_once('=').map(|(_, b)| !b.trim().is_empty()).unwrap_or(false)
}

match wasmer_run_with_map_commands(&items) {
    Err(e) if e.to_string().contains("host path cannot be empty") => {
        eprintln!("fix or drop mapping: {items:?}");
        Err(e)
    }
    other => other,
}

When it happens

Trigger: Passing a --map-command item like `ls=` or `ls= ` where the text after '=' trims to empty during prepare().

Common situations: Truncated flag value in a script (empty variable interpolation, e.g. --map-command ls=$CMD where CMD is unset); trailing '=' typo; list splitting producing a dangling '=' segment.

Related errors

• Invalid --map-command flag - alias cannot be empty: '{item}'
• The argument to --cwd must be an absolute path
• Read-only journal file does not exist: {journal:?}
• Cannot pre-open the current directory twice: '--volume=.' mu
• must be a valid path string

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