wasmerio/wasmer · error

The argument to --cwd must be an absolute path

Error message

The argument to --cwd must be an absolute path

What it means

wasmer run validates the --cwd flag before configuring the WASIX WASI environment. If the provided current-directory argument does not start with '/', the builder refuses to set it as the guest's working directory. WASIX requires absolute paths for cwd because the guest filesystem has no notion of the host's relative directory context.

Source

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

                }
            }

            if !root_layers.is_empty() {
                let existing_root = mount_fs
                    .filesystem_at(Path::new("/"))
                    .expect("root fs builder should always mount /");
                mount_fs.set_mount(
                    Path::new("/"),
                    Arc::new(OverlayFileSystem::new(
                        ArcFileSystem::new(existing_root),
                        root_layers,
                    )),
                )?;
            };

            if let Some(cwd) = self.cwd.as_ref() {
                if !cwd.starts_with("/") {
                    bail!("The argument to --cwd must be an absolute path");
                }
                builder = builder.current_dir(cwd.clone());
            }

            // Open the root of the new filesystem
            builder = builder
                .mount_fs(mount_fs)
                .preopen_dir(Path::new("/"))
                .unwrap();

            let dot_path = if have_current_dir {
                PathBuf::from(MAPPED_CURRENT_DIR_DEFAULT_PATH)
            } else {
                PathBuf::from("/")
            };

            builder.add_preopen_build(|p| {
                p.directory(&dot_path)

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

1. Convert the argument to an absolute path, e.g. use "$PWD" or $(realpath .) instead of "."
2. Drop the --cwd flag entirely if the default (root) working directory is acceptable
3. In wrappers/scripts, resolve the path with canonicalize/pathlib.abspath before passing --cwd

Example fix

// before
wasmer run app.wasm --cwd ./workspace
// after
wasmer run app.wasm --cwd "$(realpath ./workspace)"

use std::path::Path;
fn ensure_absolute_cwd(cwd: &str) -> Result<(), String> {
    let p = Path::new(cwd);
    if p.is_absolute() {
        Ok(())
    } else {
        Err(format!("--cwd must be absolute, got {cwd:?}; use std::fs::canonicalize first"))
    }
}

fn is_absolute_path(p: &str) -> bool { std::path::Path::new(p).is_absolute() }

match wasmer_run_with_cwd(cwd) {
    Err(e) if e.to_string().contains("must be an absolute path") => {
        let abs = std::fs::canonicalize(cwd)?;
        wasmer_run_with_cwd(abs.to_str().unwrap())
    }
    other => other,
}

When it happens

Trigger: Passing a relative path to --cwd, e.g. `wasmer run app.wasm --cwd .` or `--cwd ./build` in prepare() -> WasiEnvironmentBuilder::current_dir.

Common situations: Running wasmer from a shell with `--cwd $PWD` where a variable holds a relative path; scripting with `--cwd .`; CI configs that assume host-relative paths work; moving commands from containers (where relative cwd is tolerated) to wasmer.

Related errors

• Invalid --map-command flag - alias cannot be empty: '{item}'
• Invalid --map-command flag - host path cannot be empty: '{it
• must be a valid path string
• dir must be a valid string
• Read-only journal file does not exist: {journal:?}

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