What causes "dir must be a valid string" in wasmerio/wasmer?

Ensure the dir path is valid UTF-8 (rename the directory or use an ASCII-safe path)

dir must be a valid string

Error message

dir must be a valid string

What it means

When constructing a WASI run configuration for a single directory argument (Self constructor in the WASI runner), the host dir PathBuf is converted to a guest string with .to_str().expect(...). A directory path that is not valid UTF-8 causes this panic, because the guest path is represented as a String.

Source

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

        let (instance, wasi_env) = builder.instantiate_ext(module.clone(), module_hash, store)?;

        Ok((wasi_env, instance))
    }

    pub fn for_binfmt_interpreter() -> Result<Self> {
        let dir = std::env::var_os("WASMER_BINFMT_MISC_PREOPEN")
            .map(Into::into)
            .unwrap_or_else(|| PathBuf::from("."));
        Ok(Self {
            deny_multiple_wasi_versions: true,
            env_vars: std::env::vars_os()
                .map(|(name, value)| Ok((utf8_env_part(name)?, utf8_env_part(value)?)))
                .collect::<Result<_>>()?,
            volumes: vec![MappedDirectory {
                host: dir.clone(),
                guest: dir
                    .to_str()
                    .expect("dir must be a valid string")
                    .to_string(),
            }],
            ..Self::default()
        })
    }

    fn prepare_package_loader(
        &self,
        env: &WasmerEnv,
        client: Arc<dyn HttpClient + Send + Sync>,
    ) -> Result<BuiltinPackageLoader> {
        let checkout_dir = env.cache_dir().join("checkouts");
        let tokens = tokens_by_authority(env)?;

        let loader = BuiltinPackageLoader::new()
            .with_cache_dir(checkout_dir)
            .with_shared_http_client(client)
            .with_tokens(tokens);

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

Ensure the dir path is valid UTF-8 (rename the directory or use an ASCII-safe path)
Convert with lossy conversion on your side before passing (replace invalid bytes) if a lossy name is acceptable
Sanitize the source of the path (env vars, argv) to valid UTF-8 before constructing the WASI state
Upgrade wasmer for graceful handling of non-UTF-8 paths

Example fix

// before
let dir = std::env::current_dir()?; // may be non-UTF-8
// after
let dir_str = std::env::current_dir()?.into_os_string().into_string()
    .map_err(|_| anyhow::anyhow!("dir must be valid UTF-8"))?;
let dir = PathBuf::from(dir_str);

Defensive patterns

Strategy: validation

Validate before calling

let dir = std::path::Path::new(raw_dir);
if dir.to_str().is_none() {
    return Err(anyhow::anyhow!("--dir path must be valid UTF-8"));
}

Type guard

fn valid_dir(p: &std::path::Path) -> Option<&str> { p.to_str() }

Try / catch

std::panic::catch_unwind(|| build_wasi_state(dir))
    .map_err(|_| anyhow::anyhow!("dir path is not valid UTF-8"))?

Prevention

Validate UTF-8 of every directory path before constructing WasiState
Sanitize paths sourced from env vars and argv
Prefer String paths in your config layer, converting from OsString explicitly with error handling
Test the CLI with unusual path encodings in CI

When it happens

Trigger: Creating the WASI environment with a directory (e.g. from `wasmer run --dir <path>` or an API equivalent) whose path contains non-UTF-8 bytes, hitting the expect at wasi.rs:700.

Common situations: Passing a mount/dir path built from raw OS bytes on Linux; programmatically constructing WasiEnv with paths taken from non-UTF-8 environment variables or filesystem listings.

Related errors

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