astrid-runtime/astrid · error

delta output length differs from its header

Error message

delta output length differs from its header

What it means

`apply_delta` finishes decoding and checks that the reconstructed output length equals the `logical_bytes` declared in the delta header. A mismatch means the delta operations themselves are inconsistent with the header — the decoder refuses to return output that silently disagrees with the declared size.

Source

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

                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 }
    }

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

View on GitHub (pinned to affd8760f4)

Solutions

1. Regenerate the delta with encode_delta so header and operations are written together consistently.
2. Check whether the delta file was truncated; compare its size against the source record.
3. Verify the delta is being paired with the correct base version.
4. Validate header logical_bytes against the target file size before applying.

fn header_matches_target(encoded: &[u8], target_logical_bytes: u64) -> bool {
    // logical_bytes is the u64 after the magic
    encoded.get(5..13)
        .map(|b| u64::from_le_bytes(b.try_into().unwrap()) == target_logical_bytes)
        .unwrap_or(false)
}

match apply_delta(&base_bytes, &encoded) {
    Err(e) if e.to_string().contains("length differs from its header") => {
        eprintln!("delta header/ops inconsistent; regenerate the delta");
    },
    r => r?,
}

When it happens

Trigger: Calling `apply_delta` on a delta whose operation stream reconstructs fewer or more bytes than the header's logical_bytes field — e.g. the header was edited, operations were truncated, or the header was written for different content than the ops.

Common situations: Partially written or truncated delta blobs; hand-patched delta files; applying a delta against a mismatched base after header reuse.

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

• unknown delta operation
• 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/b66fb15326adb2fa. Report an issue: GitHub.