BoundaryML/baml · error

honest interface fragment for `{}` failed to serialize: {e}

Error message

honest interface fragment for `{}` failed to serialize: {e}

What it means

During bytecode cache validation, baml re-derives a file's 'honest' interface fragment (callable throws set) via export_callable_throws_fragment and serializes it with borsh. If borsh serialization of the freshly derived fragment fails, this error is thrown, aborting the cache verify flow. It indicates the freshly derived type data could not be encoded to bytes.

Source

Thrown at baml_language/crates/baml_cli/src/bytecode_cache.rs:2047

        // served artifact is the manifest-resident fragment blob (seeds
        // project from the manifest, not from unit payloads), so that copy is
        // what the oracle must compare.
        let clean_files = compute_dirty_partition(db, package, &manifest).clean_files;

        for entry in &manifest.files {
            if !clean_files.contains(&entry.rel_path) || entry.callable_throws_fragment.is_empty() {
                continue;
            }
            let full = root.join(&entry.rel_path);
            let Some(sf) = db.get_file(&full) else {
                continue; // file removed — never seeded
            };
            let honest =
                baml_db::baml_compiler2_hir_ty::package_interface::export_callable_throws_fragment(
                    db, sf,
                );
            let honest_bytes = borsh::to_vec(&honest).map_err(|e| {
                anyhow::anyhow!(
                    "honest interface fragment for `{}` failed to serialize: {e}",
                    entry.rel_path
                )
            })?;
            if honest_bytes != entry.callable_throws_fragment {
                anyhow::bail!(
                    "BAML_CACHE_VERIFY: cached interface fragment for `{}` differs from a fresh \
                     derivation ({} cached vs {} fresh bytes). A clean file's stored fragment is \
                     a stale substitute — the throws-taint closure failed to dirty a file whose \
                     `callable_throws` changed, so the seeded value would be \
                     wrong. Please report this.",
                    entry.rel_path,
                    entry.callable_throws_fragment.len(),
                    honest_bytes.len(),
                );
            }
        }
        Ok(())

View on GitHub (pinned to bd85ce9dee)

Solutions

  1. Delete the `.baml` bytecode cache directory and re-run the build to recompute fragments from scratch.
  2. Update baml-cli and baml_db crates to matching versions (schema drift between crates causes encode failures).
  3. If reproducible on a clean cache, reduce interface size or file a bug with the offending .baml file; borsh encode failures on derived fragments are compiler-internal bugs.

Example fix

// before
let honest_bytes = borsh::to_vec(&honest).map_err(|e| anyhow!("honest interface fragment for `{}` failed to serialize: {e}", entry.rel_path))?;
// after
// no user-side fix; clear cache and retry
// rm -rf .baml && baml build
Defensive patterns

Strategy: try-catch

Try / catch

// match on the anyhow error and check message starts with "honest interface fragment"
if let Err(e) = baml_build() {
    if e.to_string().contains("failed to serialize") {
        std::fs::remove_dir_all(".baml").ok(); // clear cache and retry
    }
}

Prevention

When it happens

Trigger: Running `baml build`/cache verification with BAML_CACHE_VERIFY enabled (or the internal honest-recompute path) where borsh::to_vec on export_callable_throws_fragment(db, sf) returns Err — e.g. a fragment containing a container exceeding borsh's u32 length limits, or a serialization schema mismatch in the HIR type structures.

Common situations: Very large generated interfaces with thousands of callables tripping borsh length encodings; internal schema drift between the hir_ty fragment type and its borsh derive after a compiler upgrade; corrupted incremental compilation state producing a fragment borsh cannot encode.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

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