astrid-runtime/astrid · error

required system migration receipt is missing: {}

Error message

required system migration receipt is missing: {}

What it means

`validate_existing_proofs` requires a stored proof for every component named `system:*`. If validation reaches a system component with no proof recorded (it was not skipped by earlier continue branches), this error is thrown. System components are mandatory migration targets, so their receipts cannot be absent.

Source

Thrown at crates/astrid-kernel/src/legacy_migration_barrier/ledger.rs:426

                    "principal migration component has no ordinary-home receipt: {}",
                    component.name
                ),
            ));
        }
        if let Some(current) = proofs.get(&component.name) {
            if current != &component.destination_proof {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    format!(
                        "destination receipt changed for migration component {}",
                        component.name
                    ),
                ));
            }
            continue;
        }
        if component.name.starts_with("system:") {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!(
                    "required system migration receipt is missing: {}",
                    component.name
                ),
            ));
        }
        // A current UID's immutable receipt/marker cannot silently disappear.
        // Deleted historical UIDs are intentionally allowed to have no live
        // projection, and an originally absent component remains absent when
        // its ledger proof was explicitly recorded as such.
        if is_live_principal_component(&component.name, directory)
            && (component.source.present || !component.destination_proof.is_absent())
        {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!(
                    "live principal migration receipt is missing: {}",

View on GitHub (pinned to affd8760f4)

Solutions

  1. Restore the missing system receipt from a trusted backup of the migrations directory.
  2. If no backup exists, delete the ledger and receipts and run the full migration (initialize_fresh_layout / migrate_legacy_layout) to regenerate them.
  3. Stop editing the ledger manually; system receipts must be produced by the migration itself.

Example fix

// before: ledger missing system: entry
$ cp <backup>/ledger.json <migrations-dir>/ledger.json
// after: or full regeneration
$ rm <migrations-dir>/ledger.json && astrid migrate
Defensive patterns

Strategy: validation

Validate before calling

for c in components.iter().filter(|c| c.name.starts_with("system:")) {
    if !proofs.contains_key(&c.name) {
        eprintln!("missing system receipt: {}", c.name);
    }
}

Try / catch

match resume_existing_layout(...) {
    Err(e) if e.to_string().contains("required system migration receipt is missing") => {
        eprintln!("restore ledger from backup or re-run full migration");
    }
    r => r?,
}

Prevention

When it happens

Trigger: validate_existing_proofs (via resume_existing_layout or existing_layout_requires_receipts_for_live_immutable_components) processes a component starting with `system:` that has no corresponding entry in the collected proofs.

Common situations: The ledger was partially restored or hand-pruned, dropping a system receipt; an interrupted migration wrote the component list but crashed before recording the system proof; a newer/older ledger schema dropped the entry.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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