capsule ' ' release selector declared version , but the…

Error message

capsule '{expected}' release selector declared version {declared_version}, but the installed manifest reports {}

What it means

validate_batch_install verifies that each capsule installed by a batch/distro install matches what the distro declared. When the distro's release selector declared a specific version but the installer's resulting manifest reports a different version, it bails with this message. This guards against installing a capsule other than the pinned release (e.g. because a registry served a different artifact or the selector was resolved incorrectly).

Solutions

Compare the declared version in the distro's release selector with the version in the installed capsule's manifest and align them (usually update the distro pin to the version actually published).
Clear any capsule/install cache and rerun the batch install so the correct pinned artifact is fetched.
If the installed version is correct, update Distro.toml's declared version to match, then rerun init.
Check the registry/index for the pinned version's availability; if it was yanked, pick an existing version.

Example fix

// before (Distro.toml)
[[releases]]
name = "codegen"
version = "1.2.0"   # no longer published; installer resolved 1.3.0
// after
[[releases]]
name = "codegen"
version = "1.3.0"

Defensive patterns

Strategy: validation

Validate before calling

// before install
let declared = release.selector.version.as_deref().unwrap_or("");
if !declared.is_empty() {
    // resolve the artifact version from the registry first and compare
    assert_eq!(resolved.version, declared, "distro pin {} != registry {}", declared, resolved.version);
}

Try / catch

match result {
    Err(e) if e.to_string().contains("declared version") => eprintln!("pin/registry drift: {e}; update Distro.toml"),
    Err(e) => return Err(e),
    Ok(v) => Ok(v),
}

Prevention

Keep distro version pins generated/updated by tooling, not by hand.
Refresh registries/caches before installs so resolution matches the pin.
Pin exact versions and verify published artifacts exist for each pin.
Run init in CI to catch pin drift early.

When it happens

Trigger: Running a batch install (via install_capsules_with_resume) where Distro.toml declares a non-empty version for a capsule and the installed Capsule.toml manifest's version differs from declared_version.

Common situations: A distro pins capsule version 1.2.0 but the registry resolves/installs 1.3.0; a stale cache or mirror serves an older/newer capsule; the distro file was hand-edited to a version that no longer matches published artifacts.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at crates/astrid-cli/src/commands/init.rs:867

            .collect::<Vec<_>>()
            .join(", ");
        bail!(
            "distro declared capsule '{expected}', but the checked installer reported [{actual}]"
        );
    }
    let installed = outcome
        .installed
        .into_iter()
        .next()
        .expect("length checked");
    if installed.id != *expected {
        bail!(
            "distro declared capsule '{expected}', but the checked installer reported '{}'",
            installed.id
        );
    }
    if !declared_version.is_empty() && installed.version != declared_version {
        bail!(
            "capsule '{expected}' release selector declared version {declared_version}, but the installed manifest reports {}",
            installed.version
        );
    }
    if let Some(expected_ref) = expected_ref
        && outcome.resolved_ref.as_deref() != Some(expected_ref)
    {
        bail!(
            "capsule '{expected}' signed ref {expected_ref} did not match installed ref {:?}",
            outcome.resolved_ref
        );
    }
    Ok(VerifiedBatchInstall {
        version: installed.version,
        wasm_hash: installed.wasm_hash,
        resolved_ref: outcome.resolved_ref,
        skipped: installed.skipped,
    })

View on GitHub (pinned to affd8760f4)