wasmerio/wasmer · error

must be a valid path string

Error message

must be a valid path string

What it means

When enumerating mapped WASI volumes, pre-opened directories (stored as PathBuf/OsString) are converted to guest path strings with .to_str().expect(...). If a pre-opened directory path contains invalid UTF-8, the conversion cannot succeed and the CLI panics with this message. Host paths on Unix may legitimately be non-UTF-8.

Source

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

        //
        // Checking for multiple wasi versions is handled outside this function.
        get_wasi_versions(module, false)
    }

    /// Checks if a given module has any WASI imports at all.
    pub fn has_wasi_imports(module: &Module) -> bool {
        // Get the wasi version in non-strict mode, so no other imports
        // are allowed
        get_wasi_versions(module, false).is_some()
    }

    pub(crate) fn all_volumes(&self) -> Vec<MappedDirectory> {
        self.volumes
            .iter()
            .cloned()
            .chain(self.pre_opened_directories.iter().map(|d| MappedDirectory {
                host: d.clone(),
                guest: d.to_str().expect("must be a valid path string").to_string(),
            }))
            .chain(self.mapped_dirs.iter().cloned())
            .collect_vec()
    }

    pub fn prepare(
        &self,
        module: &Module,
        program_name: String,
        args: Vec<String>,
        rt: Arc<dyn Runtime + Send + Sync>,
    ) -> Result<WasiEnvBuilder> {
        let args = args.into_iter().map(|arg| arg.into_bytes());

        let map_commands = self
            .map_commands
            .iter()
            .map(|map| map.split_once('=').unwrap())

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

1. Rename the directory/path to contain only valid UTF-8 characters
2. Run wasmer from a directory whose full absolute path is valid UTF-8
3. Avoid pre-opening the offending directory; map an ASCII-safe parent path instead
4. Upgrade wasmer so non-UTF-8 paths are handled with an error instead of a panic

Example fix

// before: run from a non-UTF-8 path
wasmer run app.wasm --dir .
// after: from an ASCII-safe path
cd /home/user/project && wasmer run app.wasm --dir .

fn assert_utf8_path(p: &std::path::Path) -> Result<(), String> {
    p.to_str().map(|_| ()).ok_or_else(|| format!("path {:?} is not valid UTF-8", p))
}
// call for every --dir / pre-opened dir before running

fn is_utf8_path(p: &std::path::Path) -> bool { p.to_str().is_some() }

std::panic::catch_unwind(|| wasi.all_volumes())
    .map_err(|_| anyhow::anyhow!("non-UTF-8 path in WASI volumes"))?

When it happens

Trigger: Running `wasmer run` (or the WASI runner) in a directory (or with a pre-opened dir configured) whose absolute path contains non-UTF-8 bytes, causing all_volumes() to panic while building MappedDirectory list.

Common situations: Working inside a directory created with raw bytes in its name on Linux; legacy filesystem encodings; mounting the current directory `.` when the cwd path is non-UTF-8.

Related errors

• dir must be a valid string
• The argument to --cwd must be an absolute path
• wasmer_env_set_memory() is not supported
• Unable to determine the wasmer dir: {e}
• Symlinks in wasi::fd_read

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