astrid-runtime/astrid · error

requires non-empty NAME=PATH

Error message

{flag} requires non-empty NAME=PATH

What it means

The CLI flag (--path-style specification parser) requires a NAME=PATH pair; this fires when the '=' is present but either side is an empty string. parse_path_specification validates that both the logical name and the filesystem path are non-empty before returning them to parse_options or parse_git_specification.

Solutions

1. Supply both a non-empty name and a non-empty path separated by '=', e.g. '--flag evidence=chunks.bin'.
2. Check the shell variables feeding the flag are set and non-empty (quote them: "--flag ${NAME}=${PATH}").
3. Run the tool with --help (print_help) to see the expected NAME=PATH syntax.

Example fix

// before
mytool --flag =out.bin
// after
mytool --flag evidence=out.bin

fn valid_spec(s: &str) -> bool {
    match s.split_once('=') {
        Some((name, path)) => !name.is_empty() && !path.is_empty(),
        None => false,
    }
}

fn parse_spec(s: &str) -> Option<(String, String)> {
    s.split_once('=').filter(|(n, p)| !n.is_empty() && !p.is_empty()).map(|(n, p)| (n.to_owned(), p.to_owned()))
}

match parse_options(args) {
    Ok(opts) => run(opts),
    Err(e) if e.to_string().contains("NAME=PATH") => eprintln!("usage: --flag NAME=PATH\n{e}"),
    Err(e) => eprintln!("{e:#}"),
}

When it happens

Trigger: Passing '--flag =/some/path' (empty name), '--flag name=' (empty path), or '--flag =' to any flag handled by parse_path_specification; e.g. a trailing '=' from a shell script variable that came up empty.

Common situations: Shell scripts interpolating environment variables like '--flag $NAME=$PATH' where one variable is unset; users typing 'name= ' with trailing whitespace stripped to empty; copy-pasting examples with placeholder names.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• byte value must be non-negative and finite
• capsule ' ': branch/rev require building from source and…
• capsule name ' ' is invalid (must match ^[a-z][a-z0-9-]*$)
• capsule ' ': tag must not be empty
• capsule ' ': tag must not contain surrounding whitespace

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

Appendix: source

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

    }
    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\
         \x20                          Add up to 32 real versions without temporary files\n\
         \x20 --no-synthetic           Exclude deterministic public fixtures\n\
         \x20 --sketch-only            Skip the CDC comparison and measure sketches only\n\
         \x20 --target-kib N           Compare profiles around N KiB (repeatable)\n\
         \x20 --output PATH            Write compact JSON to PATH instead of stdout\n\

View on GitHub (pinned to affd8760f4)