BAML_CACHE_VERIFY: cached diagnostics for `{}` differ from a

Error message

BAML_CACHE_VERIFY: cached diagnostics for `{}` differ from a fresh check ({} cached vs {} fresh). The cached per-file diagnostics are a stale substitute — please report this.

What it means

This is BAML's built-in cache verification check (BAML_CACHE_VERIFY). After serving diagnostics from the bytecode cache, it re-runs db.check_file on the same source and compares; if the cached diagnostic set differs from the freshly computed one, the cache served stale per-file diagnostics and the library deliberately fails loudly and asks for a report, because silent staleness would mislead users.

Source

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

        let clean_files = compute_dirty_partition(db, package, &manifest).clean_files;
        for entry in &manifest.files {
            if !clean_files.contains(&entry.rel_path) {
                continue; // dirty — always re-checked, never served from cache
            }
            let full = root.join(&entry.rel_path);
            let Some(sf) = db.get_file(&full) else {
                continue; // file removed — never served
            };
            let Some(served) =
                crate::diagnostics_cache::rehydrate_file_blob(db, root, &entry.diagnostics)
            else {
                continue; // poison / undecodable — would degrade to a re-check
            };
            // What an honest run produces for this file: `check_file` output only
            // (the package-level set is never cached, so it is excluded here too).
            let fresh = db.check_file(sf);
            if !diagnostic_sets_equal(&served, &fresh) {
                anyhow::bail!(
                    "BAML_CACHE_VERIFY: cached diagnostics for `{}` differ from a fresh check \
                     ({} cached vs {} fresh). The cached per-file diagnostics are a stale \
                     substitute — please report this.",
                    entry.rel_path,
                    served.len(),
                    fresh.len(),
                );
            }
        }
        Ok(())
    }

    /// Load the previous manifest for the verify oracle, bypassing the
    /// `plan_reuse` verify short-circuit (verify must still compare against
    /// whatever manifest is on disk).
    fn load_prev_manifest_for_verify(&self) -> Option<ProjectManifest> {
        self.load_decoded(&self.manifest_key, "manifest")
    }

View on GitHub (pinned to bd85ce9dee)

Solutions

Clear the bytecode cache directory and re-run — stale blobs are discarded and diagnostics are recomputed.
Upgrade or align baml CLI/library versions across the team so cache writers and readers use the same compiler version.
Report this to the baml maintainers as the message requests, including the cache state and versions.
Temporarily disable the bytecode cache (run uncached) if you need unverified diagnostics immediately.

Example fix

// before: replaying cache across compiler versions
// (cache dir from baml 0.x reused by 0.y)
// after: invalidate on upgrade
rm -rf .baml_cache && baml build

Defensive patterns

Strategy: fallback

Try / catch

match result {
    Err(e) if e.to_string().contains("BAML_CACHE_VERIFY") => {
        eprintln!("cache served stale diagnostics; bypassing cache");
        clear_cache_dir();
        run_uncached()
    }
    other => other?,
}

Prevention

Clear the cache directory after upgrading the baml toolchain.
Pin the same baml version across all team members and CI so cached blobs are compatible.
Bump/rotate the cache directory when project configuration that affects diagnostics changes.
Never edit or hand-craft cached diagnostic blobs; treat the cache as opaque.
If it fires on a stable setup, file the bug report the message requests instead of working around it silently.

When it happens

Trigger: verify_and_store (or the verify pass) loads cached diagnostics for entry.rel_path, computes the fresh result with db.check_file(sf), and diagnostic_sets_equal finds a mismatch — e.g. the cache key missed an input that affects diagnostics (dependency, config, compiler version change), or the cached blob was written by a different compiler version.

Common situations: Upgrading baml without clearing the cache so old diagnostic blobs are replayed; project config (source root, generator settings) changed in ways the cache key doesn't capture; a genuine cache-correctness bug — the message explicitly requests a bug report.

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