feat(develop-docs): Spec max_cache_size for offline caching

[sentry-junior]

Adds a Cache Limits section to the offline caching spec. It defines max_cache_size (a byte limit on the envelope cache) alongside the existing max_cache_items, so SDKs can bound how much disk space the cache uses and not just how many envelopes it holds.

Context: getsentry/sentry-java#3136 and getsentry/team-mobile#163 proposed maxCacheSize but left the default and edge cases open.

What the spec covers:

• max_cache_size defaults to 512 MiB. With only max_cache_items (30), the cache can grow to 30 envelopes of up to 200 MiB each (Relay's envelope limit, and sentry-cocoa's default maxAttachmentSize). 512 MiB still fits one maximum-size envelope.
• 0 disables either limit, so users can rely on size only (or count only). If both are 0, the cache is unbounded and SDKs should warn.
• Exceeding either enabled limit triggers eviction. Both are enforced before each write, and SHOULD be enforced at SDK init too.
• Size is the envelope's on-disk file size (compressed if stored compressed). Only envelope files count; session files, crash markers, and native SDK data don't count and aren't deleted.
• Envelopes are evicted oldest-first, only as many as needed. Each eviction records a cache_overflow client report and moves the session init flag, matching what sentry-java and sentry-cocoa do for maxCacheItems today.
• An envelope that alone exceeds the limit isn't cached and doesn't evict others. The SDK tries to send it directly, otherwise drops it with a cache_overflow client report.
• Crash handlers MAY skip enforcement and leave it to the next init.
• Changing max_cache_items = 0 from "cache nothing"/invalid to "no limit", and enabling the size limit by default, are behavior changes, so SDKs SHOULD ship them in a major version.

Prior art: sentry-native already has cache_max_items (30), cache_max_size and cache_max_age (both default 0, off), where 0 disables a limit. sentry-unreal maps CacheMaxItems = 0 to unlimited on mobile. Today sentry-java and sentry-cocoa treat maxCacheItems = 0 as "cache nothing", and sentry-dotnet rejects it.

Open questions: whether to also spec a max_cache_age (sentry-native has one, sentry-cocoa hard-codes 90 days) and whether crash envelopes should be evicted last.

via roman.

--

View Junior Session [Sentry]

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 16, 2026 11:27am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-docs	Ignored	Preview	Oct 16, 2026 11:27am UTC