BoundaryML/baml · error · io::Error

invalid sha256 blob digest length {}; expected {} hex charac

Error message

invalid sha256 blob digest length {}; expected {} hex characters

What it means

BlobRef::validate checks that a sha256 blob digest is exactly SHA256_HEX_LEN (64) hex characters long. This error fires when the stored digest string has a different length, meaning the blob reference is malformed and cannot correspond to a real SHA-256 hash. It is returned as an io::Error with InvalidData kind from normalized_digest and all blob read/write paths.

Source

Thrown at baml_language/crates/bex_events/src/value/artifact.rs:45

        for byte in digest {
            let _ = write!(&mut hex, "{byte:02x}");
        }
        Self {
            algorithm: Self::ALGORITHM_SHA256.to_string(),
            digest: hex,
            size_bytes: bytes.len(),
        }
    }

    pub fn validate(&self) -> io::Result<()> {
        if self.algorithm != Self::ALGORITHM_SHA256 {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!("unsupported blob algorithm `{}`", self.algorithm),
            ));
        }
        if self.digest.len() != Self::SHA256_HEX_LEN {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!(
                    "invalid sha256 blob digest length {}; expected {} hex characters",
                    self.digest.len(),
                    Self::SHA256_HEX_LEN
                ),
            ));
        }
        if !self.digest.bytes().all(|byte| byte.is_ascii_hexdigit()) {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                "invalid sha256 blob digest; expected only hex characters",
            ));
        }
        Ok(())
    }

    fn normalized_digest(&self) -> io::Result<String> {

View on GitHub (pinned to bd85ce9dee)

Solutions

Recompute the digest with SHA-256 over the blob bytes and store the full 64-character lowercase hex string.
Check the digest string for truncation or accidental whitespace/newlines; trim nothing away and verify len == 64.
If the digest came from another tool, confirm it emits sha256 hex and not base64 or a different algorithm; fix the algorithm field accordingly.

Example fix

// before
let blob_ref = BlobRef { algorithm: "sha256", digest: short_digest.to_string(), .. };
// after
assert_eq!(digest.len(), 64);
let blob_ref = BlobRef { algorithm: "sha256", digest: full_sha256_hex(blob_bytes), .. };

Defensive patterns

Strategy: validation

Validate before calling

fn valid_sha256_hex(digest: &str) -> bool {
    digest.len() == 64 && digest.bytes().all(|b| b.is_ascii_hexdigit())
}
if !valid_sha256_hex(&blob_ref.digest) { /* fix or recompute digest before use */ }

Type guard

fn is_sha256_digest(s: &str) -> bool { s.len() == 64 && s.bytes().all(|b| b.is_ascii_hexdigit()) }

Try / catch

match blob_ref.normalized_digest() {
    Ok(digest) => { /* proceed */ }
    Err(e) if e.kind() == io::ErrorKind::InvalidData => eprintln!("bad blob ref: {e}"),
    Err(e) => return Err(e),
}

Prevention

Always generate digests via the library's BlobRef::sha256 helper instead of hand-building strings.
Store digests as lowercase hex of exactly 64 characters; add a unit assertion where digests are created.
Never truncate digests for display and then reuse the shortened string as a reference.

When it happens

Trigger: Constructing or deserializing a BlobRef whose digest string length != 64 (e.g. a truncated, empty, or base64-encoded digest), then calling normalized_digest(), write_blob(), read_blob(), or path_for().

Common situations: Manually editing event/bundle files, copying digests with surrounding whitespace stripped incorrectly or truncated in logs, using a different hash algorithm (e.g. sha1, 40 hex chars) while still declaring algorithm=sha256, or hand-crafting BlobRef values in tests/tools.

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

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/488867ea54ea7cde. Report an issue: GitHub.