{"record":{"id":"88a0d2900c803b64","repo":"astrid-runtime/astrid","slug":"astrid-init-cannot-override-the-operator-enforced","errorCode":null,"errorMessage":"astrid init cannot override the operator-enforced distro in ASTRID_ENFORCED_DISTRO","messagePattern":"astrid init cannot override the operator-enforced distro in ASTRID_ENFORCED_DISTRO","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-cli/src/dispatch.rs","lineNumber":283,"sourceCode":"fn resolve_init_distro_with(\n    requested: Option<String>,\n    enforced: Option<OsString>,\n) -> Result<String> {\n    let Some(enforced) = enforced else {\n        return non_empty_distro_source(requested).ok_or_else(|| {\n            anyhow::anyhow!(\n                \"astrid init requires --distro <@owner/repo, URL, local Distro.toml, or .shuttle> unless ASTRID_ENFORCED_DISTRO is set by an embedding launcher; Astrid Runtime does not choose a product distro\"\n            )\n        });\n    };\n    let enforced = enforced.into_string().map_err(|_| {\n        anyhow::anyhow!(\"ASTRID_ENFORCED_DISTRO must contain a valid UTF-8 distro source\")\n    })?;\n    if enforced.is_empty() {\n        anyhow::bail!(\"ASTRID_ENFORCED_DISTRO must not be empty\");\n    }\n    if requested.is_some() {\n        anyhow::bail!(\n            \"astrid init cannot override the operator-enforced distro in ASTRID_ENFORCED_DISTRO\"\n        );\n    }\n    Ok(enforced)\n}\n\nfn non_empty_distro_source(source: Option<String>) -> Option<String> {\n    source.filter(|source| !source.is_empty())\n}\n\n/// Route the root capsule-verb shorthand (`astrid <verb> [args…]`).\n///\n/// Built-in verbs never reach here — clap matches a declared `Commands`\n/// variant before the `external_subcommand` catch-all. An unrecognised\n/// token that is a near-miss of a built-in is rejected with a \"did you\n/// mean …?\" hint and exits `2` **without booting the daemon**, mirroring\n/// the clap parse error this catch-all replaced. Only a non-near-miss\n/// token is forwarded to daemon-backed capsule-verb resolution, which","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-cli/src/dispatch.rs#L265-L301","documentation":"After validating `ASTRID_ENFORCED_DISTRO`, `resolve_init_distro_with` rejects any explicit distro source passed on the command line. When an operator has enforced a distro via the environment, `astrid init <source>` cannot override it, so the command fails closed with this message.","triggerScenarios":"Running `astrid init <some-distro>` while `ASTRID_ENFORCED_DISTRO` is set to a non-empty value (i.e. `requested.is_some()` and `enforced` is valid).","commonSituations":"Developers on operator-managed machines trying to init a personal or newer distro; documentation examples that predate the enforcement policy; scripts passing a distro argument unconditionally in environments where the env var is set.","solutions":["Run `astrid init` without a distro argument; the enforced distro from `ASTRID_ENFORCED_DISTRO` will be used.","Ask the operator to change or remove `ASTRID_ENFORCED_DISTRO` if a different distro is genuinely needed.","Use a machine/environment where the enforcement variable is not set."],"exampleFix":"// before (with ASTRID_ENFORCED_DISTRO set in the environment)\nastrid init my-custom-distro\n// after\nastrid init  # uses ASTRID_ENFORCED_DISTRO","handlingStrategy":"validation","validationCode":"if std::env::var_os(\"ASTRID_ENFORCED_DISTRO\").is_some() && distro_arg.is_some() {\n    eprintln!(\"ASTRID_ENFORCED_DISTRO is set; dropping the explicit distro argument\");\n    distro_arg = None;\n}","typeGuard":"fn can_pass_explicit_distro(requested: &Option<String>) -> bool {\n    std::env::var_os(\"ASTRID_ENFORCED_DISTRO\").is_none() || requested.is_none()\n}","tryCatchPattern":"match astrid::init(opts) {\n    Err(e) if e.to_string().contains(\"cannot override the operator-enforced distro\") => {\n        eprintln!(\"rerun `astrid init` with no distro argument to use the enforced distro\");\n    }\n    other => other?,\n}","preventionTips":["Check `echo $ASTRID_ENFORCED_DISTRO` before passing an explicit distro to `astrid init`.","Drop distro arguments from automation scripts on operator-managed machines.","Coordinate with operators when a different distro is required instead of overriding locally."],"tags":["cli","env-var","policy"],"backgroundTag":"conflicting-config-options","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"}