BAML_CACHE_VERIFY: cached interface fragment for `{}` differ

Error message

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.

What it means

BAML_CACHE_VERIFY compares a cached file's stored callable_throws_fragment against a freshly derived one. When the bytes differ, the incremental cache's dirtying logic (throws-taint closure) failed to mark the file stale after its callable_throws changed, so the cached value is wrong and a warm build would produce incorrect results. This is explicitly an internal cache-soundness bug the maintainers ask be reported.

Source

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

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

    /// The `BAML_CACHE_SAMPLED_VERIFY` knob: `Some(false)` disables sampling,
    /// `Some(true)` forces it on every warm compile (tests want determinism),
    /// `None` leaves the default 1/32 gate. Any other value is treated as unset.
    fn sampled_verify_force() -> Option<bool> {

View on GitHub (pinned to bd85ce9dee)

Solutions

Delete the incremental bytecode cache (`.baml` / profiles-v1 sibling cache) and rebuild clean.
Re-run with BAML_CACHE_VERIFY=1 after a clean build to confirm the fresh cache verifies.
Report the reproduction to the baml maintainers — the taint closure missing a dirty is a compiler bug.

Example fix

# before
baml build  # warm cache, possibly stale throws
# after
rm -rf .baml && BAML_CACHE_VERIFY=1 baml build

Defensive patterns

Strategy: try-catch

Try / catch

if let Err(e) = build() {
    if e.to_string().contains("BAML_CACHE_VERIFY") {
        fs::remove_dir_all(".baml"); // discard unsound cache, rebuild clean
    }
}

Prevention

Wipe the cache after editing throws clauses in dependency files
Run a clean build in CI rather than restoring warm caches across branches
Run BAML_CACHE_VERIFY=1 occasionally on warm builds to catch stale seeds early

When it happens

Trigger: Building with BAML_CACHE_VERIFY=1 where a file is considered 'clean' in the incremental plan but its re-derived export_callable_throws_fragment bytes differ from entry.callable_throws_fragment — i.e. throws propagation changed without the file being dirtied.

Common situations: Editing a function's `throws` clause (or a callee's) in one file and relying on a warm build; compiler upgrades that changed throws-taint rules while old cache entries persist; multi-file dependency graphs where taint closure misses a dependent file.

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

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