BAML_CACHE_SAMPLED_VERIFY: the incremental cache served a ST

Error message

BAML_CACHE_SAMPLED_VERIFY: the incremental cache served a STALE callable-throws seed for `{rel}` ({} served vs {} honest bytes). This is a cache-soundness bug — a warm build would infer different throws than a clean one. Re-run with BAML_CACHE_VERIFY=1 for the full compare and please report this (file `{rel}`, artifact: callable-throws fragment).

What it means

Sampled verification re-derives a file's callable-throws fragment honestly and compares its borsh bytes with the cached seed. On mismatch the incremental cache served a stale callable-throws seed, meaning a warm build would infer different throws than a clean one. This is flagged as a cache-soundness bug to report.

Source

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

                    fresh.len(),
                );
            }
        }

        // (2) Served `callable_throws` fragment vs an honest derivation. The
        // served copy is the manifest-resident blob (what the seeds project
        // from); an empty fragment seeds nothing, so there is no served
        // artifact to check.
        if let Some(fragment) = plan.clean_fragments.get(rel)
            && !fragment.is_empty()
        {
            let honest =
                baml_db::baml_compiler2_hir_ty::package_interface::export_callable_throws_fragment(
                    honest_db, sf,
                );
            let honest_bytes = borsh::to_vec(&honest)?;
            if honest_bytes != *fragment {
                anyhow::bail!(
                    "BAML_CACHE_SAMPLED_VERIFY: the incremental cache served a STALE \
                     callable-throws seed for `{rel}` ({} served vs {} honest bytes). This is a \
                     cache-soundness bug — a warm build would infer different throws than a clean \
                     one. Re-run with BAML_CACHE_VERIFY=1 for the full compare and please report \
                     this (file `{rel}`, artifact: callable-throws fragment).",
                    fragment.len(),
                    honest_bytes.len(),
                );
            }
        }
        Ok(())
    }

    /// Install the immutable stdlib typed-interface seed (a per-toolchain
    /// build constant). Returns whether the seed was served; gated off under
    /// `BAML_CACHE_VERIFY` so the oracle exercises the honest path.
    pub(crate) fn seed_stdlib_interface(&self, db: &mut ProjectDatabase) -> bool {
        !Self::verify_enabled()

View on GitHub (pinned to bd85ce9dee)

Solutions

Clear the incremental cache directory and rebuild clean.
Re-run with BAML_CACHE_VERIFY=1 for the full comparison before reporting.
Report the repro to baml maintainers; the seed should never diverge for a truly clean file.

Example fix

# before
baml build  # warm cache, stale throws seed
# 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("STALE callable-throws seed") {
        fs::remove_dir_all(".baml");
        return build();
    }
    return Err(e);
}

Prevention

Wipe cache after changing throws declarations anywhere in the project
Pin one compiler version per cache; regenerate after upgrades
Use clean builds for release/verification runs

When it happens

Trigger: Build with sampled verify where borsh::to_vec(export_callable_throws_fragment(honest_db, sf)) != *fragment for a file the plan considered clean.

Common situations: Changing `throws` declarations in dependency files without the taint closure dirtying dependents; stale caches reused after compiler upgrades; CI restoring caches across branches.

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/0b6de71a8cf77ce2. Report an issue: GitHub.