astrid-runtime/astrid · error

--grant-capsules requires a resolved distro: grants apply…

Error message

--grant-capsules requires a resolved distro: grants apply to the capsules a distro installs

What it means

validate_grant_capsules enforces that the --grant-capsules flag is only used together with a resolved distro, because grants are computed from the capsules a distro installs. Passing --grant-capsules during init without a distro is rejected with this bail.

Solutions

1. Add the distro argument (or select a distro) so init resolves one before applying --grant-capsules.
2. Remove --grant-capsules if no distro install is intended and grant capsules explicitly by other means.
3. Fix the wrapper script so the flag is only emitted when a distro is present.

Example fix

// before
astrid init --grant-capsules            # no distro
// after
astrid init --distro my-distro --grant-capsules

// shell pre-check before invoking init
if [[ " $args " == *" --grant-capsules "* && -z "$DISTRO" ]]; then
  echo "--grant-capsules requires --distro"; exit 2;
fi

match result {
    Err(e) if e.to_string().contains("--grant-capsules requires a resolved distro") => eprintln!("add a --distro argument or drop --grant-capsules"),
    Err(e) => return Err(e),
    Ok(v) => Ok(v),
}

When it happens

Trigger: Running `init --grant-capsules ...` when no distro was resolved/present in the init context (distro_present == false).

Common situations: A user copies an init command from docs that includes --grant-capsules but forgets the distro argument/URL; a script builds the command conditionally and the distro portion was dropped.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• byte value must be non-negative and finite
• capsule ' ': branch/rev require building from source and…
• capsule name ' ' is invalid (must match ^[a-z][a-z0-9-]*$)
• capsule ' ': tag must not be empty
• capsule ' ': tag must not contain surrounding whitespace

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

Appendix: source

Thrown at crates/astrid-cli/src/commands/init_grant.rs:54

        newly_installed.to_vec()
    }
}

/// Guard: `--grant-capsules` may only be honoured alongside a distro
/// install, because the grant set is exactly the capsules that distro
/// installs. `distro_present` is whether a non-empty distro source
/// resolved. Pure so the invariant is unit-testable without a network
/// install.
///
/// # Errors
/// Returns an error when `grant_capsules` is set but no distro source is
/// present.
pub(super) fn validate_grant_capsules(
    grant_capsules: bool,
    distro_present: bool,
) -> anyhow::Result<()> {
    if grant_capsules && !distro_present {
        bail!(
            "--grant-capsules requires a resolved distro: grants apply to the capsules a distro installs"
        );
    }
    Ok(())
}

/// Complete the mandatory second Distro Apply stage for the authenticated
/// caller. The kernel derives both target and member set from its admitted
/// lock; no capsule names cross this boundary.
pub(crate) async fn apply_self_grant(caller: &PrincipalId) -> anyhow::Result<()> {
    eprintln!(
        "{}",
        Theme::info(&format!("Granting Distro capsule access to '{caller}'..."))
    );
    let mut client = crate::admin_client::connect_for_workspace_as(caller.clone())
        .await
        .context("Distro install committed, but connecting for the self grant failed")?;
    let body = client

View on GitHub (pinned to affd8760f4)