astrid-runtime/astrid · error

delta magic mismatch

Error message

delta magic mismatch

What it means

`DeltaCursor::expect` consumes `expected.len()` bytes and compares them to an expected literal (e.g. the delta format's magic prefix). Any difference bails with this error, meaning the input is not a delta blob in the expected format — the decoder refuses to parse unrecognizable bytes.

Source

Thrown at crates/astrid-storage-chunker-evidence/src/sketch.rs:715

    }
    Ok(output)
}

struct DeltaCursor<'a> {
    bytes: &'a [u8],
    offset: usize,
}

impl<'a> DeltaCursor<'a> {
    const fn new(bytes: &'a [u8]) -> Self {
        Self { bytes, offset: 0 }
    }

    fn expect(&mut self, expected: &[u8]) -> Result<()> {
        if self.take(expected.len())? == expected {
            Ok(())
        } else {
            bail!("delta magic mismatch")
        }
    }

    fn skip(&mut self, length: usize) -> Result<()> {
        self.take(length).map(|_| ())
    }

    fn byte(&mut self) -> Result<u8> {
        self.take(1)?
            .first()
            .copied()
            .ok_or_else(|| anyhow::anyhow!("truncated delta byte"))
    }

    fn u64(&mut self) -> Result<u64> {
        Ok(u64::from_le_bytes(
            self.take(8)?
                .try_into()

View on GitHub (pinned to affd8760f4)

Solutions

1. Verify the input is the output of encode_delta (or an equivalent stored delta), not raw file content.
2. Check the first bytes of the blob against the expected magic to identify what was actually passed.
3. Re-encode or re-store the delta if the blob is corrupted.
4. If the magic changed across versions, migrate old deltas before decoding.

const DELTA_MAGIC: &[u8] = b"ASTRD";
fn has_delta_magic(bytes: &[u8]) -> bool {
    bytes.starts_with(DELTA_MAGIC)
}

fn is_delta_blob(bytes: &[u8]) -> bool {
    bytes.len() > 5 && bytes.starts_with(b"ASTRD")
}

if !is_delta_blob(&blob) {
    eprintln!("refusing to decode: not a delta blob (bad magic)");
} else {
    apply_delta(&base_bytes, &blob)?;
}

When it happens

Trigger: Calling `apply_delta` with bytes that do not begin with the expected delta magic/sig — feeding a full file, a JSON record, an empty buffer, or a delta from a different format version into the decoder.

Common situations: Wrong blob fetched from the object store; format version change altering the magic; file corruption overwriting the header.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• unknown delta operation
• delta output length differs from its header
• delta has trailing bytes
• encoded evidence delta did not reconstruct its target
• cannot remove capsule authority while an install transaction

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