bounded provider catalog cache exceeds its write limit

Error message

bounded provider catalog cache exceeds its write limit

What it means

write_bounded_cache serializes the bounded cache into a PersistedProviderCatalogs envelope and re-checks that the final JSON size fits limits.max_bytes before the atomic write. If the whole envelope still exceeds the byte budget after bounding, persistence is refused rather than writing an oversized file.

Solutions

Shrink the cache before persisting (evict stale/failed scopes) so the envelope fits
Increase limits.max_bytes for the persistence config
Write only the protected/essential scopes instead of the full cache
Clear the on-disk cache file and let the app rebuild a smaller cache

Defensive patterns

Strategy: validation

Validate before calling

if persisted_envelope_len(&cache)? > limits.max_bytes {
    // evict stale scopes or raise limits before calling write_bounded_cache
}

Try / catch

if let Err(e) = write_bounded_cache(&path, &cache, protected, limits) {
    if e.to_string().contains("exceeds its write limit") {
        // fall back to persisting only the protected scope
        write_bounded_cache(&path, &protected_only, None, limits)?;
    } else { return Err(e); }
}

Prevention

Budget total cache size across scopes, not just per scope
Evict failed/stale scopes before persisting
Raise limits.max_bytes deliberately if caches are legitimately large
Delete an oversized cache file and let it rebuild smaller

When it happens

Trigger: Calling persist_scope/persist_failure_scope (or the round-trip test) when, after bounded_cache_for_persistence compaction and schema_version envelope wrapping, the serialized cache exceeds limits.max_bytes.

Common situations: Many scopes each near the per-scope limit whose combined size blows the total budget; a stale large cache being persisted with new, smaller limits.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/609abe80e4cae97e. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/provider_catalog_live.rs:864

    while persisted_envelope_len(&cache)? > limits.max_bytes {
        let _removed_rows = evict_next(&mut cache)?;
    }

    Ok(cache)
}

fn write_bounded_cache(
    path: &Path,
    cache: ProviderCatalogCache,
    protected_scope: Option<(&str, &str)>,
    limits: CachePersistenceLimits,
) -> Result<()> {
    let cache = bounded_cache_for_persistence(cache, protected_scope, now_unix(), limits)?;
    let envelope = PersistedProviderCatalogs {
        schema_version: CACHE_SCHEMA_VERSION,
        cache,
    };
    anyhow::ensure!(
        persisted_envelope_len(&envelope.cache)? <= limits.max_bytes,
        "bounded provider catalog cache exceeds its write limit"
    );
    atomic_write_json(path, &envelope)
}

fn persist_scope(cache: &ProviderCatalogCache, provider: &str, fingerprint: &str) -> bool {
    let Some(path) = cache_path() else {
        return false;
    };
    let provider = canonical_provider_scope(provider);
    let result = (|| -> Result<()> {
        let lock_file = open_cache_lock(&cache_lock_path(&path))?;
        let mut lock = fd_lock::RwLock::new(lock_file);
        let _guard = lock
            .write()
            .with_context(|| format!("write-lock provider catalog cache {}", path.display()))?;
        // Merge only the exact scope this process just changed into the latest

View on GitHub (pinned to 73e0f67d83)