zeroclaw-labs/zeroclaw · error

manifest exec binary is not a regular file: {}

Error message

manifest exec binary is not a regular file: {}

What it means

Final filesystem check on the exec binary in `load_one_plugin`: once existence, canonicalization, and containment pass, the path must be a regular file. Directories, FIFOs, sockets, and device nodes that happen to carry the expected name are rejected — `exists()` alone is intentionally not trusted for something that will be executed.

Source

Thrown at crates/zeroclaw-hardware/src/loader.rs:236

                    "binary_path": raw_binary_path.display().to_string(),
                    "error": format!("{}", e),
                })),
            "cannot canonicalize plugin binary path"
        );
        anyhow::Error::msg(format!(
            "cannot canonicalize binary path {}: {e}",
            raw_binary_path.display()
        ))
    })?;
    if !binary_path.starts_with(&canonical_plugin_dir) {
        anyhow::bail!(
            "manifest exec binary escapes plugin directory: {} is not under {}",
            binary_path.display().to_string(),
            canonical_plugin_dir.display()
        );
    }
    if !binary_path.is_file() {
        anyhow::bail!(
            "manifest exec binary is not a regular file: {}",
            binary_path.display()
        );
    }

    let name = manifest.tool.name.clone();
    let version = manifest.tool.version.clone();
    let tool: Box<dyn Tool> = Box::new(SubprocessTool::new(manifest, binary_path));

    Ok(LoadedPlugin {
        name,
        version,
        tool,
    })
}

/// Return the path `~/.zeroclaw/tools/` using the `directories` crate.
pub fn plugin_tools_dir() -> Result<PathBuf> {

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Point `binary` at the executable file itself, including its file name
2. Replace any directory or FIFO placeholder with the real compiled binary

Example fix

# before
[exec]
binary = "bin"
# after
[exec]
binary = "bin/my-tool"

let binary = plugin_dir.join(&manifest.exec.binary);
if !binary.is_file() {
    anyhow::bail!("exec binary must be a regular file: {}", binary.display());
}

When it happens

Trigger: `binary = "bin"` pointing at a directory; a named pipe or device node created where the executable is expected; scaffolding scripts leaving placeholders behind.

Common situations: Omitting the file name so the path resolves to a directory; placeholder files created with mkfifo/mknod or by installers; a subdirectory shadowing the binary name.

Related errors

• manifest missing [tool] name
• manifest missing [tool] description
• manifest missing [exec] binary
• manifest exec binary not found: {}
• manifest exec binary escapes plugin directory: {} is not und

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/1179708f09f2fd97. Report an issue: GitHub.