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

failed to inspect imported distro locks

Error message

failed to inspect imported distro locks: {error}

What it means

`migrate_runtime` calls `legacy_distros(&staging)` to inspect imported distro lock records and wraps any failure as "failed to inspect imported distro locks". The legacy distro scan records which distro locks exist in the staged runtime so they can be carried into the receipt; an I/O error during this scan aborts the migration.

Solutions

  1. Read the wrapped inner error to find the offending lock path and fix its permissions or remove the corrupt lock file from the source.
  2. Ensure the source runtime is quiescent (runtime stopped) so lock files are not mutated mid-copy, then retry.
  3. Copy the migration as root or the same user that owns the legacy distro locks.
  4. Delete obsolete legacy distro locks from the source before migrating if they are no longer needed.
Defensive patterns

Strategy: try-catch

Validate before calling

check_source_readable(source.join("run"))?;

Try / catch

if let Some(io_err) = err.downcast_ref::<io::Error>() {
    if let Some(inner) = io_err.to_string().strip_prefix("failed to inspect imported distro locks: ") {
        eprintln!("distro lock scan failed: {inner}");
    }
}

Prevention

When it happens

Trigger: An error returned by `legacy_distros` while reading lock files under the staged runtime during `migrate_runtime` — e.g. unreadable lock files, permission issues, or entries disappearing between copy and scan.

Common situations: Importing a runtime whose legacy distro lock files have restrictive permissions or were created by another user; concurrently modifying the source while the migration copies it.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

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

                &mut entries,
            )?;
        }
        copy_wasm_blobs(&source.join("bin"), &staging.join("bin"), &mut entries)?;
        archive_inactive_activation_state(&staging, &mut entries).map_err(|error| {
            io::Error::new(
                error.kind(),
                format!("failed to preserve imported activation state: {error}"),
            )
        })?;
        ensure_no_ephemeral_data(&staging).map_err(|error| {
            io::Error::new(
                error.kind(),
                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");

View on GitHub (pinned to f6f22024fb)