astrid-runtime/astrid · error

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

In headless (non-interactive) capsule installation, `write_headless_env_fields` resolves each required `[env]` field from a supplied `--var` value, then a default, and fails if neither exists. The error tells you exactly which capsule field is missing and the two accepted remedies.

Source

Thrown at crates/astrid-cli/src/commands/capsule/install_headless.rs:48

    let existing = list_env_entries(principal, capsule_id)?;
    let existing_keys: std::collections::HashSet<String> =
        existing.into_iter().map(|entry| entry.key).collect();

    for key in order_env_keys(env_defs) {
        let def = &env_defs[&key];
        let env_key = headless_env_key(&key);
        let supplied = vars
            .get(&key)
            .cloned()
            .or_else(|| std::env::var(&env_key).ok());
        if supplied.is_none() && existing_keys.contains(&key) {
            continue;
        }
        let resolved = supplied
            .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})"
                )
            })?;

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

        if def.env_type == "secret" {
            if resolved.is_empty() {
                delete_env_entry(principal, capsule_id, &key, EnvValueKind::Secret)?;
            } else {
                set_env_entry(
                    principal,

View on GitHub (pinned to affd8760f4)

Solutions

  1. Pass the value explicitly: `--var KEY=value`
  2. Export the corresponding env var named by `headless_env_key` (e.g. `ASTRID_VAR_KEY`) before running
  3. Add a default for the field in the capsule manifest `[env]` definition if a sensible default exists

Example fix

// before
seal install @acme/my-capsule  // fails: missing API_KEY
// after
seal install @acme/my-capsule --var API_KEY=sk-...
// or: export ASTRID_VAR_API_KEY=sk-...
Defensive patterns

Strategy: validation

Validate before calling

// Before headless install, verify every required env field is satisfiable:
// for (key, def) in &manifest.env {
//     let has = vars.contains_key(key)
//         || std::env::var(headless_env_key(key)).is_ok()
//         || def.default.is_some();
//     if def.required && !has { /* fail fast with clear message */ }
// }

Try / catch

match result {
    Err(e) if e.to_string().starts_with("required value is missing") => {
        eprintln!("Supply the field via --var KEY=... or export the matching env var.");
    }
    other => other?,
}

Prevention

When it happens

Trigger: Running a headless install of a capsule whose manifest declares a required env field with no default, while the invocation supplies neither `--var key=...` for it nor sets the corresponding environment variable (`headless_env_key(key)`), and the key is not already present in the target env.

Common situations: CI/non-interactive runs of capsules that normally prompt for config; new required fields added in a capsule update that existing automation doesn't set; secrets intentionally without defaults not exported in the environment.

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/d28669b6271667c7. Report an issue: GitHub.