astrid-runtime/astrid · error

unknown delta operation

Error message

unknown delta operation

What it means

`apply_delta` decodes an encoded delta stream whose operations are tagged by a leading byte: 0 = Copy, 1 = Add. Any other op tag means the byte stream is not a delta this decoder understands — truncated/mangled data, wrong format version, or bytes that are not a delta at all were fed to the decoder.

Source

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

    let mut output = Vec::with_capacity(usize::try_from(logical_bytes)?);
    for _ in 0..operation_count {
        match cursor.byte()? {
            0 => {
                let offset = usize::try_from(cursor.u64()?)?;
                let length = usize::try_from(cursor.u64()?)?;
                let end = offset
                    .checked_add(length)
                    .ok_or_else(|| anyhow::anyhow!("delta copy range overflow"))?;
                output.extend_from_slice(
                    base.get(offset..end)
                        .ok_or_else(|| anyhow::anyhow!("delta copy is outside its base"))?,
                );
            },
            1 => {
                let length = usize::try_from(cursor.u64()?)?;
                output.extend_from_slice(cursor.take(length)?);
            },
            _ => bail!("unknown delta operation"),
        }
    }
    cursor.done()?;
    if output.len() != usize::try_from(logical_bytes)? {
        bail!("delta output length differs from its header");
    }
    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 }
    }

View on GitHub (pinned to affd8760f4)

Solutions

1. Confirm the encoded blob came from the matching `encode_delta` version; re-encode with the current library version.
2. Check for truncation/corruption of the stored delta bytes (compare length with the recorded size).
3. Ensure you're passing the delta blob, not a full file or metadata record, to apply_delta.
4. If new op codes are expected, extend apply_delta's match to decode them.

fn looks_like_delta(bytes: &[u8]) -> bool {
    // every op must start with tag 0 or 1; at minimum verify the magic header
    bytes.starts_with(b"ASTRD")
}

fn is_known_op_tag(tag: u8) -> bool {
    matches!(tag, 0 | 1)
}

match apply_delta(&base_bytes, &encoded) {
    Err(e) if e.to_string().contains("unknown delta operation") => {
        eprintln!("delta format version mismatch: re-encode with current version");
    },
    r => r?,
}

When it happens

Trigger: Calling `apply_delta` (directly or via `delta_size`) with an encoded blob whose operation tag byte is neither 0 nor 1 — e.g. passing a delta produced by a newer encoder version with additional op codes, or arbitrary/corrupted bytes.

Common situations: Version skew between encoder and decoder after a format upgrade; truncated delta files; accidentally decoding the wrong blob (e.g. a full file instead of a delta).

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

• delta output length differs from its header
• delta magic mismatch
• 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/0f5514586093626e. Report an issue: GitHub.