astrid-runtime/astrid · error

--var must be KEY=VALUE (got {item:?})

Error message

--var must be KEY=VALUE (got {item:?})

What it means

parse_cli_vars parses each --var item with split_once('='). Any item without an '=' separator cannot be split into KEY=VALUE and produces this error, echoing the offending item with {:?}. It is a CLI usage error, not a runtime failure.

Source

Thrown at crates/astrid-cli/src/commands/init.rs:73

    /// `init` installs capsules but attaches no grants and
    /// prints the manual `agent modify` command for discoverability.
    pub(crate) grant_capsules: bool,
    /// Require the signed self-contained Distro artifact used by product
    /// Apply. Ordinary `init` retains its legacy source support.
    pub(crate) require_signed: bool,
}

pub(crate) use grant::apply_self_grant;

/// Parse `--var KEY=VALUE` strings into a map.
///
/// Splits on the first `=`. A missing `=` or empty key is an error.
pub(crate) fn parse_cli_vars(raw: &[String]) -> anyhow::Result<HashMap<String, String>> {
    let mut map = HashMap::new();
    for item in raw {
        let (key, value) = item
            .split_once('=')
            .ok_or_else(|| anyhow::anyhow!("--var must be KEY=VALUE (got {item:?})"))?;
        if key.is_empty() {
            bail!("--var has an empty key (got {item:?})");
        }
        map.insert(key.to_string(), value.to_string());
    }
    Ok(map)
}

/// Enforce source flags before this flow can create runtime state.
fn validate_install_source(
    distro_source: &str,
    opts: &InitOpts,
    operator: &astrid_core::PrincipalId,
    target: &astrid_core::PrincipalId,
) -> anyhow::Result<bool> {
    let shuttle_install = distro_source.ends_with(".shuttle");
    // `--grant-capsules` is not wired for `.shuttle`; fail rather than silently
    // skip the requested grants and point at the legacy manual command.

View on GitHub (pinned to affd8760f4)

Solutions

1. Supply the variable as KEY=VALUE, e.g. --var region=eu-west-1
2. Quote the whole argument if the value contains spaces: --var "key=my value"
3. Check `astrid init --help` for the exact --var syntax
4. Improve the error to suggest the expected format with an example

Example fix

// before
astrid init --var region
// after
astrid init --var region=eu-west-1

fn valid_cli_var(item: &str) -> bool {
    match item.split_once('=') {
        Some((k, _)) => !k.is_empty(),
        None => false,
    }
}

let vars = parse_cli_vars(&raw_vars)
    .map_err(|e| { eprintln!("usage: --var KEY=VALUE\n{e}"); std::process::exit(2); })?;

When it happens

Trigger: Passing `--var foo` (missing '=value'), `--var =bar` (empty key — though that hits a separate error), or quoting mistakes like `--var "foo =bar"` where the value contains stray spaces.

Common situations: Users forgetting the value side (`--var name`), shell quoting issues (`--var key=my value` unquoted), or copy-pasting flag syntax from docs incorrectly.

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

• unknown argument {unknown:?}; use --help
• --target-kib requires an integer
• --output requires a path
• --git-history requires NAME=REPO::RELATIVE_PATH
• {flag} requires NAME=PATH

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