wasmerio/wasmer · error

cannot create debug directory: {}

Error message

cannot create debug directory: {}

What it means

base_path creates the directory where LLVM debug artifacts (pre/post-optimization IR, object files, asm) are dumped when debug directives are enabled. If std::fs::create_dir_all fails (permissions, path collisions, invalid path characters), the code panics with the path it could not create. It only runs when debug output is configured via the LLVM debug builder settings.

Source

Thrown at lib/compiler-llvm/src/config.rs:54

impl LLVMCallbacks {
    pub fn new(debug_dir: PathBuf) -> Result<Self, io::Error> {
        // Create the debug dir in case it doesn't exist
        std::fs::create_dir_all(&debug_dir)?;
        Ok(Self { debug_dir })
    }

    /// Returns the debug directory used to dump compilation artifacts.
    pub fn debug_dir(&self) -> &PathBuf {
        &self.debug_dir
    }

    fn base_path(&self, module_hash: &Option<String>) -> PathBuf {
        let mut path = self.debug_dir.clone();
        if let Some(hash) = module_hash {
            path.push(hash);
        }
        std::fs::create_dir_all(&path)
            .unwrap_or_else(|_| panic!("cannot create debug directory: {}", path.display()));
        path
    }

    pub fn preopt_ir(
        &self,
        kind: &CompiledKind,
        module_hash: &Option<String>,
        module: &InkwellModule,
    ) {
        let mut path = self.base_path(module_hash);
        path.push(function_kind_to_filename(kind, ".preopt.ll"));
        module
            .print_to_file(&path)
            .expect("Error while dumping pre optimized LLVM IR");
    }
    pub fn postopt_ir(
        &self,
        kind: &CompiledKind,

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

1. Ensure the configured debug_dir exists and is writable by the process user, or point it at a temp dir the process can create (e.g. std::env::temp_dir()).
2. Remove/replace any non-directory file that occupies the debug_dir path or its module-hash subpath.
3. Run the compilation with sufficient filesystem permissions (fix user/ACL, mount writable volume).
4. If debug artifacts are not needed, disable the LLVM debug output options so base_path is never called.

Example fix

// before
let builder = LLVMBuilder::new().debug(true).debug_dir("/var/log/llvm-dbg".into());
// after
std::fs::create_dir_all("/tmp/wasmtime-llvm-dbg").expect("create debug dir");
let builder = LLVMBuilder::new().debug(true).debug_dir("/tmp/wasmtime-llvm-dbg".into());

// Validate the debug dir before configuring the LLVM builder
let dir = std::path::Path::new("/tmp/wasmtime-llvm-dbg");
std::fs::create_dir_all(dir).expect("debug dir must be creatable and writable");
assert!(dir.is_dir(), "debug dir must not be an existing regular file");

// Panics cannot be caught with std::panic::catch_unwind (no UnwindSafe guarantee on builder internals);
// prefer validating the dir up front:
let result = std::panic::catch_unwind(|| compile_with_debug_dir(&path));
match result {
    Ok(m) => m,
    Err(_) => { eprintln!("debug dir unusable; disable LLVM debug output"); compile_without_debug()? }
}

When it happens

Trigger: Enabling LLVM debug output (e.g. `set_debug_info`/debug_dir config on the LLVM builder) where the configured debug_dir cannot be created: read-only filesystem, insufficient permissions, a non-directory file already exists at the path (or at the module-hash subpath), or an invalid path for the OS.

Common situations: Pointing debug_dir at /root-owned or read-only paths in containers; a stale regular file occupying the hash subdirectory; running the compiler as an unprivileged user while debug_dir points into a privileged location; disk full or path containing characters invalid on Windows.

Related errors

• cannot create debug directory: {}
• Unhandled inner case
• not a `sys` backend!
• Unsupported backend kind {v:?}
• unimplemented operator {operator:?}

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