required value is missing for {capsule_id}.{key} (use --var

Error message

required value is missing for {capsule_id}.{key} (use --var {key}=… or set {env_key})

What it means

Interactive capsule installs fall back to the same headless resolution when running non-interactively (`headless` flag): `collect_install_env_fields` tries the supplied value, then the derived environment variable, then the manifest default, and throws if all three are absent for a required field.

Source

Thrown at crates/astrid-cli/src/commands/capsule/install_prompts.rs:181

    for key in existing_keys {
        collected.insert(key.clone(), serde_json::Value::String(String::new()));
    }

    let mut prompted = false;
    let mut values = Vec::new();
    for key in order_env_keys(env_defs) {
        let def = &env_defs[&key];
        let value = if let Some(value) = supplied.get(&key) {
            value.clone()
        } else if existing_keys.contains(&key) {
            continue;
        } else if headless {
            let env_key = headless_env_key(&key);
            std::env::var(&env_key)
                .ok()
                .or_else(|| def.default.as_ref().map(json_value_string))
                .ok_or_else(|| {
                    anyhow::anyhow!(
                        "required value is missing for {capsule_id}.{key} \
                         (use --var {key}=… or set {env_key})"
                    )
                })?
        } else {
            if !prompted {
                eprintln!("\nThis capsule requires configuration:");
                prompted = true;
            }
            prompt_single_field(&key, def, &collected)
        };

        if !def.enum_values.is_empty() && !def.enum_values.iter().any(|item| item == &value) {
            anyhow::bail!(
                "invalid value for {capsule_id}.{key}: expected one of {}, got {value:?}",
                def.enum_values.join(", ")
            );
        }

View on GitHub (pinned to affd8760f4)

Solutions

Supply `--var KEY=value` on the install command
Set the derived environment variable (see `headless_env_key`, e.g. `ASTRID_VAR_KEY`) in the environment
Run interactively (without --headless) to be prompted for the value

Example fix

// before
CI=true astrid install @acme/my-capsule --headless  // fails: missing DATABASE_URL
// after
astrid install @acme/my-capsule --headless --var DATABASE_URL=postgres://...

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight check mirroring the fallback chain:
// let resolved = supplied
//     .or_else(|| def.default.as_ref().map(json_value_string))
//     .or_else(|| std::env::var(headless_env_key(&key)).ok());
// if resolved.is_none() { eprintln!("missing required field {key}"); }

Try / catch

match result {
    Err(e) if e.to_string().starts_with("required value is missing") => {
        eprintln!("Run interactively or provide --var KEY=... / the derived env var.");
    }
    other => other?,
}

Prevention

Avoid --headless without first exporting required env vars or passing --var
Test headless installs in CI mirroring production environment
Document required fields per capsule for operators

When it happens

Trigger: Running an install with headless mode enabled (no TTY / `--headless`) where a required `[env]` field has no default and the caller provides neither `--var key=...` nor the derived env var, and the key isn't already configured in the collection.

Common situations: Scripted installs in CI where the capsule expects a prompt; Docker/CI environments lacking the exported env var; capsule update introducing a new required field not present in saved collection state.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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