astrid init cannot override the operator-enforced distro in

Error message

astrid init cannot override the operator-enforced distro in ASTRID_ENFORCED_DISTRO

What it means

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.

Source

Thrown at crates/astrid-cli/src/dispatch.rs:283

fn resolve_init_distro_with(
    requested: Option<String>,
    enforced: Option<OsString>,
) -> Result<String> {
    let Some(enforced) = enforced else {
        return non_empty_distro_source(requested).ok_or_else(|| {
            anyhow::anyhow!(
                "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"
            )
        });
    };
    let enforced = enforced.into_string().map_err(|_| {
        anyhow::anyhow!("ASTRID_ENFORCED_DISTRO must contain a valid UTF-8 distro source")
    })?;
    if enforced.is_empty() {
        anyhow::bail!("ASTRID_ENFORCED_DISTRO must not be empty");
    }
    if requested.is_some() {
        anyhow::bail!(
            "astrid init cannot override the operator-enforced distro in ASTRID_ENFORCED_DISTRO"
        );
    }
    Ok(enforced)
}

fn non_empty_distro_source(source: Option<String>) -> Option<String> {
    source.filter(|source| !source.is_empty())
}

/// Route the root capsule-verb shorthand (`astrid <verb> [args…]`).
///
/// Built-in verbs never reach here — clap matches a declared `Commands`
/// variant before the `external_subcommand` catch-all. An unrecognised
/// token that is a near-miss of a built-in is rejected with a "did you
/// mean …?" hint and exits `2` **without booting the daemon**, mirroring
/// the clap parse error this catch-all replaced. Only a non-near-miss
/// token is forwarded to daemon-backed capsule-verb resolution, which

View on GitHub (pinned to affd8760f4)

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.

Example fix

// before (with ASTRID_ENFORCED_DISTRO set in the environment)
astrid init my-custom-distro
// after
astrid init  # uses ASTRID_ENFORCED_DISTRO

Defensive patterns

Strategy: validation

Validate before calling

if std::env::var_os("ASTRID_ENFORCED_DISTRO").is_some() && distro_arg.is_some() {
    eprintln!("ASTRID_ENFORCED_DISTRO is set; dropping the explicit distro argument");
    distro_arg = None;
}

Type guard

fn can_pass_explicit_distro(requested: &Option<String>) -> bool {
    std::env::var_os("ASTRID_ENFORCED_DISTRO").is_none() || requested.is_none()
}

Try / catch

match astrid::init(opts) {
    Err(e) if e.to_string().contains("cannot override the operator-enforced distro") => {
        eprintln!("rerun `astrid init` with no distro argument to use the enforced distro");
    }
    other => other?,
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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