astrid-runtime/astrid · error

{flag} requires NAME=PATH

Error message

{flag} requires NAME=PATH

What it means

This error comes from parse_path_specification in the chunker-evidence CLI. A NAME=PATH specification (e.g. --volume primary=/path/to/dir) was required, but the flag was given with no value at all. The library refuses to proceed because it cannot construct an evidence mapping without both a name and a path.

Source

Thrown at crates/astrid-storage-chunker-evidence/src/main.rs:223

    let (repository, relative_path) = combined
        .split_once("::")
        .ok_or_else(|| anyhow::anyhow!("--git-history requires NAME=REPO::RELATIVE_PATH"))?;
    if repository.is_empty() || relative_path.is_empty() {
        bail!("--git-history requires non-empty NAME=REPO::RELATIVE_PATH");
    }
    Ok((
        name,
        PathBuf::from(repository),
        PathBuf::from(relative_path),
    ))
}

fn parse_path_specification(
    flag: &str,
    specification: Option<String>,
) -> Result<(String, PathBuf)> {
    let specification =
        specification.ok_or_else(|| anyhow::anyhow!("{flag} requires NAME=PATH"))?;
    let (name, path) = specification
        .split_once('=')
        .ok_or_else(|| anyhow::anyhow!("{flag} requires NAME=PATH"))?;
    if name.is_empty() || path.is_empty() {
        bail!("{flag} requires non-empty NAME=PATH");
    }
    Ok((name.to_owned(), PathBuf::from(path)))
}

fn print_help() {
    println!(
        "Usage: astrid-storage-chunker-evidence [OPTIONS]\n\
         \n\
         Options:\n\
         \x20 --corpus NAME=PATH       Add a directory snapshot; paths stay out of reports\n\
         \x20 --version-chain NAME=PATH\n\
         \x20                          Add lexically ordered version files\n\
         \x20 --git-history NAME=REPO::RELATIVE_PATH\n\

View on GitHub (pinned to affd8760f4)

Solutions

1. Pass a value in NAME=PATH form after the flag, e.g. --volume primary=/data/evidence.
2. Check the argument parsing wiring so the flag's value is captured as Some(String) rather than dropped.
3. Add shell quoting so an empty variable does not silently remove the argument.

Example fix

// before
mybin --volume
// after
mybin --volume primary=/data/evidence

fn validate_path_spec(spec: &Option<String>) -> Result<(), String> {
    match spec {
        None => Err("flag requires NAME=PATH".into()),
        Some(s) if !s.contains('=') => Err("flag requires NAME=PATH".into()),
        Some(s) => {
            let (n, p) = s.split_once('=').unwrap();
            if n.is_empty() || p.is_empty() { Err("empty NAME or PATH".into()) } else { Ok(()) }
        }
    }
}

match parse_path_specification(flag, spec) {
    Ok((name, path)) => use_spec(name, path),
    Err(e) => eprintln!("usage: {flag} NAME=PATH ({e:#})"),
}

When it happens

Trigger: Calling parse_path_specification (via parse_options or parse_git_specification) with specification == None, i.e. the CLI flag was passed without any argument value after it.

Common situations: Running the binary with a flag like --volume but forgetting the value; shell scripts that build argument arrays and drop an empty variable; typos where the value was attached to a different flag.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• unknown argument {unknown:?}; use --help
• --var must be KEY=VALUE (got {item:?})
• --target-kib requires an integer
• --output requires a path
• --git-history requires NAME=REPO::RELATIVE_PATH

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/490296b061a10084. Report an issue: GitHub.