What causes "--var must be KEY=VALUE (got {item:?})" in astrid-runtime/astrid?

Write each --var item as KEY=VALUE with a literal '='

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

Error message

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

What it means

Raised in ManualInstallOptions::from_cli when a --var item does not contain an '=' separator, so it cannot be split into KEY=VALUE. split_once('=') returns None and the CLI rejects the item, naming the offending value.

Source

Thrown at crates/astrid-cli/src/commands/capsule/install.rs:66

    expected: Option<ExpectedCapsule<'a>>,
    prompt: &'a ManualInstallOptions,
}

/// Operator input policy for a manual capsule install.
#[derive(Debug, Clone, Default)]
pub(super) struct ManualInstallOptions {
    pub(super) yes: bool,
    pub(super) approve_untrusted: bool,
    pub(super) vars: HashMap<String, String>,
}

impl ManualInstallOptions {
    fn from_cli(yes: bool, approve_untrusted: bool, items: &[String]) -> anyhow::Result<Self> {
        let mut vars = HashMap::new();
        for item in items {
            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:?})");
            }
            if vars.insert(key.to_string(), value.to_string()).is_some() {
                bail!("--var '{key}' was supplied more than once");
            }
        }
        Ok(Self {
            yes,
            approve_untrusted,
            vars,
        })
    }
}

#[derive(Clone, Copy)]
pub(crate) struct OfflineCapsuleProvenance<'a> {
    pub(crate) original_source: &'a str,

View on GitHub (pinned to affd8760f4)

Solutions

Write each --var item as KEY=VALUE with a literal '='
Quote the whole argument in the shell: --var 'KEY=some value'
Check for empty keys too; the CLI rejects those separately

Example fix

// before
--var DEBUG
// after
--var DEBUG=true

Defensive patterns

Strategy: validation

Validate before calling

for item in items {
    if !item.contains('=') || item.split('=').next().unwrap().is_empty() {
        eprintln!("--var must be KEY=VALUE (got {item:?})");
        std::process::exit(2);
    }
}

Type guard

fn is_key_value(item: &str) -> bool { matches!(item.split_once('='), Some((k, _)) if !k.is_empty()) }

Try / catch

match ManualInstallOptions::from_cli(yes, approve, &items) { Err(e) => { eprintln!("{e:#}"); std::process::exit(2); }, Ok(opts) => opts }

Prevention

Always write --var KEY=VALUE with a literal '='
Quote arguments containing spaces or special characters in the shell
Deduplicate keys before passing multiple --var flags

When it happens

Trigger: Passing --var with a bare key ('DEBUG'), only a value, or using a different separator (':' or spaces) instead of '='.

Common situations: Users familiar with --env KEY VALUE style flags omitting the '=', or quoting issues in the shell swallowing the '=' sign.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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