astrid-runtime/astrid · error · anyhow::Error

astrid init requires --distro <@owner/repo, URL, local Distr

Error message

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

What it means

`astrid init` was run without a --distro source while the ASTRID_ENFORCED_DISTRO environment variable was unset. Astrid deliberately has no default product distro: the user must supply one of @owner/repo, a URL, a local Distro.toml, or a .shuttle directory, unless an embedding launcher enforces one via the env var.

Source

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

        Some(Commands::Update(args)) => {
            commands::self_update::run_self_update(args).await?;
            Ok(ExitCode::SUCCESS)
        },
        Some(Commands::External(tokens)) => dispatch_root_shorthand(tokens).await,
    }
}

fn resolve_init_distro(requested: Option<String>) -> Result<String> {
    resolve_init_distro_with(requested, std::env::var_os("ASTRID_ENFORCED_DISTRO"))
}

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)
}

View on GitHub (pinned to affd8760f4)

Solutions

1. Pass --distro with a valid source: @owner/repo, URL, path to Distro.toml, or .shuttle
2. If embedding, set ASTRID_ENFORCED_DISTRO before invoking the CLI
3. Check that the flag isn't being dropped by a wrapper script
4. Consult the distro documentation to pick a distro source

Example fix

// before
astrid init
// after
astrid init --distro @owner/repo

if std::env::var_os("ASTRID_ENFORCED_DISTRO").is_none() && !args.contains("--distro") {
    eprintln!("astrid init needs --distro or ASTRID_ENFORCED_DISTRO");
}

match astrid_init(distro) {
    Err(e) if e.to_string().starts_with("astrid init requires --distro") => {
        eprintln!("supply --distro @owner/repo, URL, Distro.toml, or .shuttle");
    }
    other => other?,
}

When it happens

Trigger: resolve_init_distro_with called with requested=None and enforced=None; i.e. `astrid init` with no --distro flag and no ASTRID_ENFORCED_DISTRO in the environment.

Common situations: New users running bare `astrid init` expecting a default; CI scripts dropping the --distro flag; embedding launchers that forgot to set ASTRID_ENFORCED_DISTRO.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• distro source '{source}' must use @owner/repo, a URL, a loca
• --offline: '{source}' is not a local file and network fetch
• redeem requires either --public-key <hex> or --keypair <name
• no corpus selected; omit --no-synthetic or pass a corpus or
• Distro.toml has no parent directory

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