{"record":{"id":"d28669b6271667c7","repo":"astrid-runtime/astrid","slug":"required-value-is-missing-for-capsule-id-key","errorCode":null,"errorMessage":"required value is missing for {capsule_id}.{key} (use --var {key}=… or set {env_key})","messagePattern":"required value is missing for (.+?)\\.(.+?) \\(use --var (.+?)=… or set (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-cli/src/commands/capsule/install_headless.rs","lineNumber":48,"sourceCode":"\n    let existing = list_env_entries(principal, capsule_id)?;\n    let existing_keys: std::collections::HashSet<String> =\n        existing.into_iter().map(|entry| entry.key).collect();\n\n    for key in order_env_keys(env_defs) {\n        let def = &env_defs[&key];\n        let env_key = headless_env_key(&key);\n        let supplied = vars\n            .get(&key)\n            .cloned()\n            .or_else(|| std::env::var(&env_key).ok());\n        if supplied.is_none() && existing_keys.contains(&key) {\n            continue;\n        }\n        let resolved = supplied\n            .or_else(|| def.default.as_ref().map(json_value_string))\n            .ok_or_else(|| {\n                anyhow::anyhow!(\n                    \"required value is missing for {capsule_id}.{key} \\\n                     (use --var {key}=… or set {env_key})\"\n                )\n            })?;\n\n        if !def.enum_values.is_empty() && !def.enum_values.iter().any(|item| item == &resolved) {\n            anyhow::bail!(\n                \"invalid value for {capsule_id}.{key}: expected one of {}, got {resolved:?}\",\n                def.enum_values.join(\", \")\n            );\n        }\n\n        if def.env_type == \"secret\" {\n            if resolved.is_empty() {\n                delete_env_entry(principal, capsule_id, &key, EnvValueKind::Secret)?;\n            } else {\n                set_env_entry(\n                    principal,","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-cli/src/commands/capsule/install_headless.rs#L30-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the value explicitly: `--var KEY=value`","Export the corresponding env var named by `headless_env_key` (e.g. `ASTRID_VAR_KEY`) before running","Add a default for the field in the capsule manifest `[env]` definition if a sensible default exists"],"exampleFix":"// before\nseal install @acme/my-capsule  // fails: missing API_KEY\n// after\nseal install @acme/my-capsule --var API_KEY=sk-...\n// or: export ASTRID_VAR_API_KEY=sk-...","handlingStrategy":"validation","validationCode":"// Before headless install, verify every required env field is satisfiable:\n// for (key, def) in &manifest.env {\n//     let has = vars.contains_key(key)\n//         || std::env::var(headless_env_key(key)).is_ok()\n//         || def.default.is_some();\n//     if def.required && !has { /* fail fast with clear message */ }\n// }","typeGuard":null,"tryCatchPattern":"match result {\n    Err(e) if e.to_string().starts_with(\"required value is missing\") => {\n        eprintln!(\"Supply the field via --var KEY=... or export the matching env var.\");\n    }\n    other => other?,\n}","preventionTips":["Inventory required [env] fields from the capsule manifest before CI runs","Set headless env vars in CI secret management, not inline","Pin capsule versions so newly added required fields don't surprise automation"],"tags":["capsule","headless","env","missing-value","cli"],"backgroundTag":"missing-required-config-field","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}