BAML_CACHE_SAMPLED_VERIFY: the incremental cache served STAL

Error message

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

What it means

Under sampled verification, baml re-runs diagnostics honestly (honest_db.check_file) for a file the incremental cache claims is clean and compares with the rehydrated cached diagnostics blob. If they differ, the cache served stale diagnostics — a warm build would report different errors than a clean one — and it bails as a cache-soundness bug.

Source

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

        plan: &ReusePlan,
        rel: &str,
    ) -> anyhow::Result<()> {
        let root = honest_package.path(honest_db);
        let full = root.join(rel);
        let Some(sf) = honest_db.get_file(&full) else {
            return Ok(()); // file vanished between planning and verify — unserved
        };

        // (1) Served diagnostics blob vs a fresh per-file check. A blob that
        // fails to rehydrate would have degraded to a re-check (never served
        // stale), so it is not a mismatch — skip it, as the full oracle does.
        if let Some(blob) = plan.clean_diagnostics.get(rel)
            && let Some(served) =
                crate::diagnostics_cache::rehydrate_file_blob(honest_db, root, blob)
        {
            let fresh = honest_db.check_file(sf);
            if !diagnostic_sets_equal(&served, &fresh) {
                anyhow::bail!(
                    "BAML_CACHE_SAMPLED_VERIFY: the incremental cache served STALE diagnostics \
                     for `{rel}` ({} served vs {} from an honest check). This is a \
                     cache-soundness bug — a warm build would report different errors than a \
                     clean one. Re-run with BAML_CACHE_VERIFY=1 for the full compare and please \
                     report this (file `{rel}`, artifact: diagnostics).",
                    served.len(),
                    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()
        {

View on GitHub (pinned to bd85ce9dee)

Solutions

Delete the bytecode/diagnostics cache and run a clean build to get correct diagnostics.
Re-run with BAML_CACHE_VERIFY=1 to obtain the full comparison and identify which file served stale data.
Report the reproduction (file `{rel}`, artifact: diagnostics) to baml maintainers.

Example fix

# before
baml build  # warm cache, stale diagnostics
# after
rm -rf .baml && baml build  # clean diagnostics

Defensive patterns

Strategy: try-catch

Try / catch

if let Err(e) = build() {
    if e.to_string().contains("served STALE diagnostics") {
        fs::remove_dir_all(".baml");
        return build(); // clean rebuild gives correct diagnostics
    }
    return Err(e);
}

Prevention

Don't share incremental caches across commits/branches in CI
Clear cache after compiler version changes
Enable sampled verification in CI to detect unsound caches before shipping

When it happens

Trigger: Running a build with sampled cache verification where plan.clean_diagnostics[rel] rehydrated via rehydrate_file_blob does not equal diagnostic_sets_equal(&served, &fresh) against honest_db.check_file(sf).

Common situations: Editing a file (or its dependencies) that the incremental dependency tracker failed to dirty; running diagnostics across compiler versions with an old cache; CI cache restored from a different commit.

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