unicity-aos/aos-ce · error · io::Error

staged runtime did not validate against its import manifest

Error message

staged runtime did not validate against its import manifest

What it means

After staging the imported runtime, `migrate_runtime` builds a `Receipt` (with schema version, source path, entries, and legacy distros) and verifies the staged tree against it via `receipt_matches`. If verification returns false, the staged runtime does not match its own import manifest, so the library raises `InvalidData` with this message instead of installing unverifiable state.

Solutions

Re-run the migration with a fresh staging directory so entries and receipt are rebuilt consistently.
Ensure nothing else has write access to the staging path (check for concurrent jobs, tmpwatch/cleanup daemons).
Verify disk health and free space — partial writes or corruption during copy are a common cause of manifest mismatch.
If the error persists, compare the staged tree against the receipt (the wrapped inner error from receipt_matches names the failing entry) to find the divergent file.

Defensive patterns

Strategy: fallback

Try / catch

match migrate_runtime(&source, &target) {
    Err(e) if e.to_string().contains("did not validate against its import manifest") => {
        clean_staging_dir();
        migrate_runtime(&source, &target)
    }
    other => other,
}

Prevention

Use a fresh, empty staging directory for every migration attempt.
Ensure no cleanup daemons or concurrent processes touch the staging path.
Check disk health and free space before long copies.

When it happens

Trigger: `receipt_matches(&staging, &receipt)` returns `Ok(false)` during `migrate_runtime` — i.e. the entry list/hashes recorded during copy no longer match the staged files, or entries were added/removed/modified after the receipt was built.

Common situations: Another process mutating the staging directory mid-migration; a copy that silently truncated/corrupted a file; staging directory reused from a previous failed run leaving stale files.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13). Data as JSON: /api/errors/9bb2c440134235c6. Report an issue: GitHub.

Appendix: source

Thrown at crates/unicity-aos-bootstrap/src/migration.rs:298

                format!("failed to validate ephemeral state exclusion: {error}"),
            )
        })?;
        entries.sort_by(|left, right| left.path.cmp(&right.path));
        let legacy_distros = legacy_distros(&staging).map_err(|error| {
            io::Error::new(
                error.kind(),
                format!("failed to inspect imported distro locks: {error}"),
            )
        })?;
        let receipt = Receipt {
            migration_version: MIGRATION_VERSION,
            schema_version: RECEIPT_SCHEMA_VERSION,
            source: source.clone(),
            entries,
            legacy_distros,
        };
        if !receipt_matches(&staging, &receipt).map_err(|error| {
            io::Error::new(
                error.kind(),
                format!("failed to validate staged import receipt: {error}"),
            )
        })? {
            return invalid("staged runtime did not validate against its import manifest");
        }
        let staged_receipt = write_staged_receipt(&receipt_path, &receipt)?;
        let backup = replace_target(&target, &staging)?;
        if let Err(error) = finalize_receipt(&staged_receipt, &receipt_path) {
            remove_path(&receipt_path)?;
            remove_path(&staged_receipt)?;
            rollback_target(&target, &backup)?;
            return Err(error);
        }
        remove_backup(&backup)?;
        Ok(())
    })();
    if result.is_err() && staging.exists() {

View on GitHub (pinned to f6f22024fb)