{"record":{"id":"2e8b3e183885c864","repo":"astrid-runtime/astrid","slug":"required-value-is-missing-for-capsule-id-key-2e8b3e","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_prompts.rs","lineNumber":181,"sourceCode":"    for key in existing_keys {\n        collected.insert(key.clone(), serde_json::Value::String(String::new()));\n    }\n\n    let mut prompted = false;\n    let mut values = Vec::new();\n    for key in order_env_keys(env_defs) {\n        let def = &env_defs[&key];\n        let value = if let Some(value) = supplied.get(&key) {\n            value.clone()\n        } else if existing_keys.contains(&key) {\n            continue;\n        } else if headless {\n            let env_key = headless_env_key(&key);\n            std::env::var(&env_key)\n                .ok()\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        } else {\n            if !prompted {\n                eprintln!(\"\\nThis capsule requires configuration:\");\n                prompted = true;\n            }\n            prompt_single_field(&key, def, &collected)\n        };\n\n        if !def.enum_values.is_empty() && !def.enum_values.iter().any(|item| item == &value) {\n            anyhow::bail!(\n                \"invalid value for {capsule_id}.{key}: expected one of {}, got {value:?}\",\n                def.enum_values.join(\", \")\n            );\n        }","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-cli/src/commands/capsule/install_prompts.rs#L163-L199","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nCI=true astrid install @acme/my-capsule --headless  // fails: missing DATABASE_URL\n// after\nastrid install @acme/my-capsule --headless --var DATABASE_URL=postgres://...","handlingStrategy":"validation","validationCode":"// Pre-flight check mirroring the fallback chain:\n// let resolved = supplied\n//     .or_else(|| def.default.as_ref().map(json_value_string))\n//     .or_else(|| std::env::var(headless_env_key(&key)).ok());\n// if resolved.is_none() { eprintln!(\"missing required field {key}\"); }","typeGuard":null,"tryCatchPattern":"match result {\n    Err(e) if e.to_string().starts_with(\"required value is missing\") => {\n        eprintln!(\"Run interactively or provide --var KEY=... / the derived env var.\");\n    }\n    other => other?,\n}","preventionTips":["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"],"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"}