installed capsule ' ' version disagrees between…

Error message

installed capsule '{}' version disagrees between Capsule.toml ({}) and meta.json ({})

What it means

After reading both the capsule manifest (Capsule.toml) and install metadata (meta.json), the validator requires them to agree on the installed version. A disagreement means the install is inconsistent and bails with this message naming both versions.

Solutions

Reinstall the capsule (rerun init) so Capsule.toml and meta.json are written consistently.
Delete the capsule's install directory and perform a clean install.
Check for interrupted upgrades in logs and avoid concurrent installs to the same target.
If intentional downgrade/upgrade was manual, redo it with the CLI rather than editing files.

Example fix

// meta.json says 1.0.0 but Capsule.toml says 1.1.0 after a botched upgrade
// before
$ ls target/  # mixed files from two versions
// after
$ rm -rf <capsule-target-dir> && astrid init --distro my-distro

Defensive patterns

Strategy: validation

Validate before calling

// cross-check before granting
let manifest = read_manifest(dir)?;
let meta = read_meta(dir)?;
if manifest.package.version != meta.version {
    eprintln!("inconsistent install: Capsule.toml {} vs meta.json {}",
        manifest.package.version, meta.version);
}

Try / catch

match result {
    Err(e) if e.to_string().contains("version disagrees") => eprintln!("reinstall capsule for consistent metadata"),
    Err(e) => return Err(e),
    Ok(v) => Ok(v),
}

Prevention

Avoid concurrent installs/upgrades to the same capsule target.
Retry interrupted upgrades from scratch rather than partially.
Use the CLI for upgrades so both files are updated atomically.
Verify version agreement after any manual intervention.

When it happens

Trigger: manifest.package.version != meta.version for a locked capsule — Capsule.toml says one version while meta.json records another.

Common situations: An upgrade replaced Capsule.toml but failed to update meta.json (interrupted install); a manual file copy swapped in a new capsule over old metadata; parallel installs racing on the same target directory.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

            );
        }
        let meta = super::super::capsule::meta::read_meta(&target_dir).ok_or_else(|| {
            anyhow::anyhow!(
                "Distro.lock capsule '{}' has no readable install metadata for target '{}'",
                capsule.name,
                target
            )
        })?;
        if manifest.package.version != meta.version {
            bail!(
                "installed capsule '{}' version disagrees between Capsule.toml ({}) and meta.json ({})",
                expected,
                manifest.package.version,
                meta.version
            );
        }
        if !capsule.version.is_empty() && meta.version != capsule.version {
            bail!(
                "Distro.lock capsule '{}' expects version {}, but meta.json reports {}",
                capsule.name,
                capsule.version,
                meta.version
            );
        }
        validate_locked_wasm(
            home,
            &expected,
            &manifest,
            meta.wasm_hash.as_deref(),
            &capsule.hash,
            store,
        )?;
        installed.push(expected.as_str().to_string());
    }
    Ok(installed)
}

View on GitHub (pinned to affd8760f4)