astrid-runtime/astrid · error

unsupported schema-version {} (expected {SCHEMA_VERSION})

Error message

unsupported schema-version {} (expected {SCHEMA_VERSION})

What it means

validate_manifest checks DistroManifest.schema_version against the compile-time SCHEMA_VERSION constant and rejects any other value. The distro manifest format evolves; loading a manifest written for a different schema version is unsupported rather than guessed at.

Source

Thrown at crates/astrid-cli/src/commands/distro/validate.rs:80

/// Checks that cannot be expressed in serde alone:
/// - Schema version is supported
/// - Distro ID format
/// - Distro version is valid semver
/// - astrid-version (if set) is valid semver requirement
/// - No duplicate capsule names
/// - At least one capsule
/// - At least one capsule with role = "uplink"
/// - Variable references in capsule env resolve to defined variables
/// - Requires version strings are valid semver requirements
#[allow(
    clippy::too_many_lines,
    reason = "flat sequence of independent validation checks; \
              inlining keeps the full ruleset auditable in one place"
)]
pub(crate) fn validate_manifest(manifest: &DistroManifest) -> anyhow::Result<()> {
    // Schema version.
    if manifest.schema_version != SCHEMA_VERSION {
        anyhow::bail!(
            "unsupported schema-version {} (expected {SCHEMA_VERSION})",
            manifest.schema_version,
        );
    }

    // Distro ID format.
    if !is_valid_id(&manifest.distro.id) {
        anyhow::bail!(
            "distro.id '{}' is invalid (must match ^[a-z][a-z0-9-]*$)",
            manifest.distro.id,
        );
    }

    // Distro version is valid semver.
    if semver::Version::parse(&manifest.distro.version).is_err() {
        anyhow::bail!(
            "distro.version '{}' is not valid semver",
            manifest.distro.version,

View on GitHub (pinned to affd8760f4)

Solutions

1. Update schema-version in Distro.toml to the version the tool expects (see the error message)
2. Upgrade or downgrade the astrid CLI to a version matching the manifest's schema-version
3. Migrate the manifest through the tool version that supports its schema, then resave

Example fix

// before
// schema-version = 1
// after
// schema-version = 2  # match the installed astrid's SCHEMA_VERSION

if manifest.schema_version != SCHEMA_VERSION {
    return Err(anyhow!("unsupported schema-version {}", manifest.schema_version));
}

When it happens

Trigger: Passing a DistroManifest parsed from a Distro.toml whose schema-version field is older or newer than the tool's SCHEMA_VERSION — e.g. a manifest produced by a different astrid version.

Common situations: Hand-edited Distro.toml with a wrong schema-version number; manifests from an older/newer astrid release; copy-pasted manifests between projects with different versions.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• capsule archive entry '{requested}' is not a regular file
• capsule archive contains duplicate entry '{path}'
• capsule archive contains unsupported entry '{path}'
• capsule provenance envelope exceeds 64 KiB
• capsule identity or version changed after authority decision

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