unicity-aos/aos-ce · error · std::io::Error

bundled executable not found at

Error message

bundled {label} executable not found at {}

What it means

ensure_runtime_executable calls fs::metadata on the bundled executable; if metadata fails with io::ErrorKind::NotFound it re-raises a NotFound error formatted "bundled {label} executable not found at {path}". This gives callers of foreground_daemon_command and ensure_runtime_available a clear, labeled message when a required bundled binary is missing.

Solutions

1. Verify the binary exists at the reported path (`ls <path>`); if missing, reinstall or repair the runtime bundle.
2. Check any absolute package override configuration points at a complete, existing bundle directory.
3. Run the bootstrap's ensure_runtime_available first so missing bundles are materialized before spawning.
4. Confirm you are using the expected installation root env variable (see validated_environment_root) and not a stale one.

Example fix

// before
let bin = PathBuf::from("/opt/unicity/old-version/bin/unicityd"); // deleted after upgrade
// after
let bin = runtime.unicity_executable_path()?; // ask the layout, don't hardcode
runtime.ensure_runtime_available()?; // materializes the bundle first

fn binary_exists(bin: &Path) -> Result<(), String> {
    if !bin.exists() {
        return Err(format!("bundled executable missing at {}; run the bootstrap/installer first", bin.display()));
    }
    Ok(())
}

match result {
    Err(e) if e.kind() == io::ErrorKind::NotFound && e.to_string().contains("executable not found") => {
        eprintln!("run `bootstrap ensure-runtime` (or reinstall the bundle) to restore the missing binary");
    }
    other => other?,
}

When it happens

Trigger: Calling ensure_runtime_executable (via foreground_daemon_command or ensure_runtime_available) with a binary Path that does not exist on disk (fs::metadata returns NotFound).

Common situations: The runtime bundle was never installed or was partially deleted; a custom absolute package override points at a nonexistent directory; wrong version root after an upgrade; PATH/override typo in configuration.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• product manifest path must be a regular file
• temporary product manifest path must be a regular file
• bundled executable must have a parent directory
• cannot construct the bundled runtime PATH
• bundled executable is not executable at

AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13). Data as JSON: /api/errors/c34fa63cb9a5b5e7. Report an issue: GitHub.

Appendix: source

Thrown at crates/unicity-aos-bootstrap/src/lib.rs:520

    /// Returns an error when the bundled executable is absent or cannot start.
    pub fn run_runtime_with_args<I, S>(&self, args: I) -> io::Result<ExitStatus>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<OsStr>,
    {
        self.spawn_runtime_with_args(args)?.wait()
    }

    fn ensure_runtime_available(&self) -> io::Result<()> {
        let binary = self.runtime_binary();
        self.ensure_runtime_executable(&binary, "runtime")?;
        self.ensure_unicity_ce_manifest().map(drop)
    }

    fn ensure_runtime_executable(&self, binary: &Path, label: &str) -> io::Result<()> {
        let metadata = fs::metadata(binary).map_err(|error| {
            if error.kind() == io::ErrorKind::NotFound {
                io::Error::new(
                    io::ErrorKind::NotFound,
                    format!(
                        "bundled {label} executable not found at {}",
                        binary.display()
                    ),
                )
            } else {
                error
            }
        })?;
        if !metadata.is_file() {
            return Err(io::Error::new(
                io::ErrorKind::NotFound,
                format!(
                    "bundled {label} executable not found at {}",
                    binary.display()
                ),
            ));

View on GitHub (pinned to f6f22024fb)