astrid-runtime/astrid · error

distro capsule '{expected}' has no concrete released version

Error message

distro capsule '{expected}' has no concrete released version or tag

What it means

Batch/distro capsule installs must pin an exact released version or tag; `install_capsule_batch` refuses to run with an unpinned refspec because distro capsules must be reproducibly resolvable. It throws when `refspec.version` and `refspec.tag` are both `None`.

Source

Thrown at crates/astrid-cli/src/commands/capsule/install_batch.rs:52

    /// sent. This lets init avoid treating a resume as a newly landed grant.
    pub(crate) skipped: bool,
}

#[derive(Debug)]
pub(crate) struct BatchInstallOutcome {
    pub(crate) installed: Vec<InstalledCapsuleOutcome>,
    pub(crate) resolved_ref: Option<String>,
}

/// Install without prompting, returning the identities that actually landed.
pub(crate) async fn install_capsule_batch(
    source: &str,
    expected: &CapsuleId,
    workspace: bool,
    refspec: &RefSpec,
    principal: &astrid_core::PrincipalId,
) -> anyhow::Result<BatchInstallOutcome> {
    anyhow::ensure!(
        refspec.version.is_some() || refspec.tag.is_some(),
        "distro capsule '{expected}' has no concrete released version or tag"
    );
    super::install::BATCH_MODE.store(true, Ordering::Relaxed);
    let prompt = super::install::ManualInstallOptions::default();
    let result = super::install::install_capsule_inner(
        source,
        Some(expected.as_str()),
        workspace,
        refspec,
        principal,
        Some(expected),
        &prompt,
    )
    .await;
    super::install::BATCH_MODE.store(false, Ordering::Relaxed);
    result.map(|(installed, resolved_ref)| BatchInstallOutcome {
        installed,

View on GitHub (pinned to affd8760f4)

Solutions

1. Pass an explicit version, e.g. `--version 1.2.3`
2. Pass an explicit tag, e.g. `--tag v1.2.3`
3. If you need latest behavior, resolve the latest version yourself (query the GitHub release) then pass it as the version

Example fix

// before
install_batch("@acme/distro", RefSpec { version: None, tag: None, .. })
// after
install_batch("@acme/distro", RefSpec { version: Some("1.2.3"), tag: None, .. })

fn refspec_is_pinned(r: &RefSpec) -> bool {
    r.version.is_some() || r.tag.is_some()
}
assert!(refspec_is_pinned(&refspec), "batch install requires --version or --tag");

When it happens

Trigger: Calling `install_capsule_batch` with a `RefSpec` that has neither `version` nor `tag` set — e.g. installing latest/moving-head for a distro capsule, or a refspec built only from a branch name or digest-less default.

Common situations: Automated scripts omitting `--version`/`--tag` when batch-installing distro capsules; users expecting 'latest' semantics that batch mode deliberately forbids; migration tooling copying refspecs from interactive installs that allowed floating refs.

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

• failed to install {} capsule(s): {names}
• --var names no [env] field in {capsule_id}: {key}
• --var names no [env] field in {capsule_id}: {key}
• Capsule '{name}' is not installed.
• Capsule '{name}' is not installed.

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