LRUCache byte cap can starve tile loading into a silent, permanent livelock (and discards fully parsed tiles while full)

[stephent]

Environment

• 3d-tiles-renderer 0.5.1, three.js r170, React wrapper (/r3f)
• Google Photorealistic 3D Tiles via GoogleCloudAuthPlugin (also using
  GLTFExtensionsPlugin + Draco, TileCompressionPlugin,
  UpdateOnChangePlugin, TilesFadePlugin, LoadRegionPlugin)
• Chrome on macOS (Apple M1 Pro), narrow-FOV ground-level camera
  (photography-planning app: the camera FOV follows real lens focal
  lengths, so ~7° vertical FOV views are routine)

Summary

When the set of tiles demanded by the current view (everything the
traversal marks used at the configured errorTarget) exceeds
lruCache.maxBytesSize, loading does not degrade — it stops permanently
and silently:

1. Admission is hard-gated on !lruCache.isFull()
   (TilesRendererBase.js:857,
   :1302–1306),
   so no new tile can enter the download queue while the cache is at its
   byte cap.
2. A tile that finishes downloading and parsing while the cache is
   full is discarded outright
   (TilesRendererBase.js:1689–1695).
   The code comment says "it will be loaded again later from the disk
   cache if needed" — but the network transfer may be re-paid (Google
   serves private, max-age=14400, so it can come from disk, though
   other servers may not allow caching) and the parse cost is always
   re-paid. Worse, in the situation below it is never loaded again at
   all.
3. LRUCache.unloadUnusedContent only evicts tiles that are not in the
   used set. When the demanded working set itself is what exceeds
   maxBytesSize, everything resident is used, nothing can be evicted,
   and points 1–2 hold forever: every in-flight parse discards, the
   queues drain, tiles-load-end fires, and the renderer sits idle at a
   partially refined scene that will never improve. There is no event,
   flag, or stat that reports this state — from the outside it is
   indistinguishable from a completed load.

A milder version of the same root cause appears while the demanded set is
near (not over) the cap: loading completes but with heavy churn, because
tiles discarded at point 2 are re-requested and re-parsed on later frames.

Observed numbers (Google Photorealistic 3D Tiles)

Churn (demanded set near the cap). errorTarget: 8,
maxBytesSize: 600 MB, rural/suburban area, wide FOV. The load settled
only after 13,848 tile requests for 5,684 loaded models (2.4×), with
cachedBytes pinned within 0.03% of maxBytesSize throughout and
download admission visibly throttled. Raising maxBytesSize to 1 GB made
the identical view load with zero churn (requests == cached items) and a
working set of ~777 MB — i.e. all of the excess traffic was
discard-and-refetch.

Livelock (demanded set over the cap). Same site, errorTarget: 8,
maxBytesSize: 1 GB, camera zoomed to a ~7.5° vertical FOV (SSE demands
~7× finer geometric error, and the narrow frustum reaches deep into the
distance). Downloads (30 parallel) outran parsing (parseQueue.maxJobs
6, main thread), the cache crossed the byte cap mid-drain, and every
parse completing after that point — ~5,500 tiles of bandwidth and decode
— was discarded. Two diagnostics snapshots taken 9 minutes apart then
show:

• loaded-model count byte-identical (5,850 → 5,850),
• cachedBytes parked just above maxBytesSize,
• all queues empty, tiles-load-end long since fired,
• camera translation (which re-runs the traversal) unable to admit a
  single tile — queueTileForDownload exits at the isFull() gate.

The scene stays frozen at whatever refinement level the cap caught, with
no error and no signal.

Suggestions

Any of these would help, roughly in order of preference:

1. Backpressure instead of discard. Gate download admission on
   projected bytes (in-flight + resident) rather than discarding
   completed parses. A completed parse is the most expensive artifact in
   the pipeline; dropping it to enforce a cap that admission already
   overshot pays the cost twice (or, in the livelock, infinitely often —
   the same tiles are demanded, admitted when momentarily under cap,
   parsed, and discarded again).
2. Detect and surface starvation. When isFull() is true, the used
   set alone exceeds maxBytesSize, and the queues are empty, the
   renderer is wedged. An event (e.g. cache-starved) and/or a stat
   would let applications respond — ours now inflates errorTarget
   until demand fits, which un-wedges it within a few seconds.
3. Automatic error-target pressure. The renderer itself could treat
   "used set > maxBytesSize" as implicit error-target inflation
   (analogous to how EnforceNonZeroErrorPlugin handles a different
   degenerate case), guaranteeing the cap can never freeze refinement —
   a coarser scene instead of a stuck one.
4. At minimum, a docs note on maxBytesSize: it is a hard admission
   gate, not a soft target; if a view's demanded working set exceeds it,
   loading stalls permanently, and tiles finishing while full are
   re-downloaded/re-parsed later.

Workaround we shipped

An application-side watchdog: once per second, if lruCache.isFull() and
the download queue is idle for >2.5 s, multiply errorTarget by 1.5
(compounding, capped ×4) and dispatch needs-update; the coarser demand
marks deep tiles unused, the unloader frees them, and admission resumes.
The multiplier is held (not decayed on a byte threshold — that oscillates
and re-downloads the evicted set each cycle) until the view/preset
changes. This works, but it reconstructs state the renderer already knows
internally — hence suggestion 2.

Happy to provide the full diagnostics snapshots or test against a branch.

---

Issue details drafted with Claude Code/Fable

[jledentu-vectuel]

Hi,

I also met issues on large tilesets when memory limit of the cache is reached: the renderer stops loading more tiles, causing visual inconsistencies depending on the previous positions of the camera - some nearer tiles may be displayed with less details than farther tiles.

I noticed than CesiumJS dynamically adapts the screen space error depending on whether the cache limit is reached or not:

if (tileset.totalMemoryUsageInBytes < cacheBytes) {
    decreaseScreenSpaceError(tileset);
} else if (memoryExceeded && tiles.length > 0) {
    increaseScreenSpaceError(tileset);
}

https://github.com/CesiumGS/cesium/blob/main/packages/engine/Source/Scene/Cesium3DTileset.js#L2926

I tried to reproduce this behaviour in a plugin that changes tiles.errorTarget in update-before callback, but didn't succeeded.

[gkjohnson]

This issue is a bit hard to follow so to try to reduce it down to the core points:

When the set of tiles demanded by the current view (everything the traversal marks used at the configured errorTarget) exceeds lruCache.maxBytesSize, loading does not degrade — it stops permanently and silently

This is working as designed and loading does not stop permanently - once "used" tiles are no longer needed they can be evicted and new tiles loaded. Though I understand it's not ideal when using a smaller error target with a complex tile set as you are here. maxBytesSize is a hard cap and the renderer degrades to displaying the coarser tiles that fit, which I think is rightly suggested by the word "max". Is there a reason you expected this to not be a hard cap? If a view demands more memory than allowed then the fix is a larger cap or a larger error target. I'm not really sure what else could realistically be done here. If more content can't be loaded then tiles will look like they're "stuck".

A tile that finishes downloading and parsing while the cache is full is discarded outright

A tile's full byte size is only known after parsing and we can't reliably know how large a download buffer is before or while downloading, so downloads and parsing can't be gated on any real final size. One solution here would be to try to predict the geometry size using some kind of a running average of downloaded tiles before triggering downloads. It's imperfect but would probably be a good improvement.

There is no event, flag, or stat that reports this state — from the outside it is indistinguishable from a completed load.

The isFull() function is already documented and available to use so this is possible to check. I can add documentation for "cachedBytes" so it's more clear that this is an option for driving application decisions, too. We could add an event indicating that the shared cache has been determined to be full but ideally an app responds to growing memory use before the cache is actually full. Just responding when the cache has actually been determined to be full is probably not ideal. And I think an event has the same transparency issue as using "isFull" - users have to know it's a problem in order to know they have to use these things. A list of "limitations" or "gotchas" in the root README to surface important things users need to be aware of may be a better solution.

Automatic error-target pressure. The renderer itself could treat "used set > maxBytesSize" as implicit error-target inflation

A plugin can be written for this if you'd like to make a contribution - I'd keep it in the examples folder to start. There's a question of whether we'd want to decrease the error target again at any point if it's possible but this can get complicated to do generally without causing oscillation.

---

And one request going forward: please keep issues small and followable. Using AI to help understand a problem is fine, but a human is reading and responding to these. A short report with the core observation and a proposed change that follows the issue templates would be appreciated.

[gkjohnson]

As a first step I've updated the docs in #1701 if you'd like to take a look.

@jledentu-vectuel

I tried to reproduce this behaviour in a plugin that changes tiles.errorTarget in update-before callback, but didn't succeeded.

Adjusting the error target should work just fine but depending on your tile set and how many tiles have had to be deferred the amount you have to change this by will vary. If you feel like it's not working at all, though, feel free to open an issue and we can take a look.

[stephent]

@gkjohnson that's fair criticism. I was very pushed for time when filing this, but nonetheless should have ensured it was set out much more clearly.

Thanks for working through it nonetheless. I'll take another swing at clarifying it next week after I get home.

[andredsm]

I am facing the same problem. My domain is 3D digital twin models. So we have heavy 3D models within a small spatial region. I understand that used and loaded tiles are preserved in cache, so we can ensure scene stability. However, the current behavior can lead to inconsistencies in the scene. For example, if the user navigates through the scene and stops at some position, the visualization will likely be different if the system provides a sort of save/restore the viewpoint. In my case, I would like to use the priority function to sort both the already-cached items and the candidates, because some candidates may have higher SSE than the cached items, since SSE depends on camera distance.

[gkjohnson]

For example, if the user navigates through the scene and stops at some position, the visualization will likely be different if the system provides a sort of save/restore the viewpoint

I've already explained above that this is a graceful failure mode. Any other solutions I can think of just have other and sometimes worse failure cases. If you're working with tile sets that are reaching the cache limit there are already many options existing within the library to iteratively adjust as-needed (by checking lruCache.isFull()) or just setting them to have headroom for your use case. They are listed in the docs but I will enumerate them here:

• errorTarget: Adjust the screen space error target. Increase to reduce tiles used / free up cache, decrease to increase tiles used.
• lruCache.maxBytesSize: Adjust the maximum amount of bytes the tiles renderers are allowed to use. Increase it to allow more tiles and therefore detail to load.
• loadSiblings: Set to false to prevent off-screen sibling tiles from loading, freeing up space at the cost of gaps when turning the camera.
• loadAncestors: Set to false to prevent parent tiles from loading, freeing up space at the cost of less immediate feedback when moving the camera since only the needed tiles are loaded.
• errorFalloff & errorFalloffDensity: Parameters for increasing target error further from the camera to reduce the number of tiles loaded and detail at further distances.
• TileCompressionPlugin: Compresses tile geometry attribute buffers to smaller formats.

Additionally you can use spark.js to live-compress textures to save memory (see #1560 and #1497).

Bear in mind almost all of these (aside from maybe spark.js and tile compression plugin) are designed to be adjusted at run time based on application needs.

In my case, I would like to use the priority function to sort both the already-cached items and the candidates, because some candidates may have higher SSE than the cached items, since SSE depends on camera distance.

I can't agree that thrashing the cache and evicting currently visible tiles and then queuing new data to load is an acceptable solution. It's really just a band-aid and will cause tons of downloads and memory to constantly churn.

As I've mentioned above: It should be possible to write an "auto-adjusting" plugin that adjusts the above error settings based on the total cached bytes and fullness metrics using as simple or as complicated a metric as you'd like. I'd be open to a suggested implementation or other improvements to the TilesRenderer API surface to make this more simple to implement (a la #1722).

[gkjohnson]

Closing in favor of #1722