Cesium Core Memory

CesiumJS Memory

Overview

CesiumJS holds GPU resources (textures, buffers, shaders, a WebGL context) that the JavaScript garbage collector cannot reclaim. Dropping a reference to a Viewer, Cesium3DTileset, Primitive, or DataSource does NOT free its GPU memory. Every such object exposes an explicit destroy() that must be called.

This skill covers four failure modes:

• GPU memory leaks from skipped destroy() calls.
• The roughly 16 WebGL contexts per browser tab limit.
• WebGL context loss and recovery.
• Distinguishing a real CesiumJS leak from a retained JavaScript reference.

Verified signatures are in references/methods.md. Runnable teardown code is in references/examples.md. Failure modes are in references/anti-patterns.md.

Core Rules

• ALWAYS call destroy() on a Viewer, Cesium3DTileset, Primitive, or DataSource before dropping the last reference to it. GPU resources are NOT garbage-collected.
• After destroy(), NEVER call any method except isDestroyed(). Any other call throws DeveloperError. ALWAYS reassign the reference to undefined.
• NEVER destroy the same object twice. One owner destroys each object exactly once. NEVER wrap destroy() in a try/catch to swallow a double-destroy error; fix the ownership instead.
• ALWAYS reuse one Viewer across views. NEVER construct a fresh Viewer on every route change or component remount without destroying the previous one.
• viewer.dataSources.remove(ds) does NOT destroy the data source: the destroy parameter defaults to false. ALWAYS pass true to free it.
• scene.primitives.remove(primitive) DOES destroy the primitive by default (destroyPrimitives is true). NEVER also call primitive.destroy() after.
• ALWAYS remove every event listener (DOM and CesiumJS Event) you added before destroying the Viewer. A retained listener keeps the whole graph alive.

Quick Reference

Teardown Ordering

digraph teardown {
    "Tearing down the whole app or unmounting the map?" [shape=diamond];
    "Removing one object mid-session?" [shape=diamond];
    "Call viewer.destroy() once" [shape=box];
    "Use the owning collection's remove()" [shape=box];
    "Reassign every reference to undefined" [shape=box];

    "Tearing down the whole app or unmounting the map?" -> "Call viewer.destroy() once" [label="whole app"];
    "Tearing down the whole app or unmounting the map?" -> "Removing one object mid-session?" [label="just one object"];
    "Removing one object mid-session?" -> "Use the owning collection's remove()" [label="yes"];
    "Call viewer.destroy() once" -> "Reassign every reference to undefined";
    "Use the owning collection's remove()" -> "Reassign every reference to undefined";
}

Rule: there is exactly one owner per object. viewer.destroy() tears down the Scene and its primitive collections, so a tileset that lives in scene.primitives is freed by viewer.destroy(). NEVER also call tileset.destroy() in that case. For mid-session removal, let the owning collection do the destroy.

Correct full-teardown sequence:

1. Remove every DOM and CesiumJS Event listener you added.
2. Destroy any ScreenSpaceEventHandler you constructed yourself.
3. Call viewer.destroy() once.
4. Reassign viewer and every cached tileset/primitive/handler to undefined.

Destroy Patterns

// Full teardown of a Viewer.
function teardown(viewer) {
  if (viewer && !viewer.isDestroyed()) {
    viewer.destroy();
  }
  return undefined; // assign the return value back to the variable
}

viewer = teardown(viewer);

// Remove a tileset mid-session. The collection destroys it.
const removed = scene.primitives.remove(tileset);
tileset = undefined; // do NOT call tileset.destroy() afterwards

// Remove a data source mid-session. The `true` is mandatory.
viewer.dataSources.remove(dataSource, true);
dataSource = undefined;

The isDestroyed() guard before destroy() is correct and is not a fallback: it prevents a double-destroy DeveloperError when teardown can be reached by more than one code path (for example a React unmount plus an explicit close button). It does NOT mask a bug; double-destroy is a real ownership question.

Tileset GPU Budget

A Cesium3DTileset caches tile content in GPU memory. Two properties bound it:

• cacheBytes : the GPU memory budget for cached tiles. Default 536870912 bytes (512 MiB).
• maximumCacheOverflowBytes : extra memory allowed beyond cacheBytes when the current view needs it. Default 536870912 bytes (512 MiB).

const tileset = await Cesium.Cesium3DTileset.fromIonAssetId(96188, {
  cacheBytes: 256 * 1024 * 1024,            // 256 MiB on a constrained device
  maximumCacheOverflowBytes: 128 * 1024 * 1024,
});

ALWAYS lower cacheBytes for memory-constrained devices (mobile, embedded kiosks). The legacy property maximumMemoryUsage was deprecated in 1.107 and removed in 1.110. NEVER emit maximumMemoryUsage; it does not exist in 1.124+.

The WebGL Context Budget

Browsers cap the number of live WebGL contexts per tab at roughly 16. Each Viewer and CesiumWidget owns exactly one context. viewer.destroy() does not always release the context immediately (CesiumGS/cesium issue #11533), so rapid create/destroy cycles exhaust the budget.

• ALWAYS reuse a single long-lived Viewer. Swap data sources and tilesets in and out instead of rebuilding the Viewer.
• NEVER mount a new Viewer per route or per component render without destroying the previous one first.
• Symptom of exhaustion: a console warning about too many active WebGL contexts, and a newly created Viewer renders a blank canvas.

WebGL Context Loss

A WebGL context can be lost when the GPU is under memory pressure (the CONTEXT_LOST_WEBGL condition). Handle it on two surfaces:

// 1. The standard DOM event on the canvas.
viewer.canvas.addEventListener("webglcontextlost", (event) => {
  event.preventDefault(); // required to allow a later restore
}, false);

// 2. The CesiumJS render-loop error event.
viewer.scene.renderError.addEventListener((scene, error) => {
  console.error("Render error:", error);
});

scene.renderError fires when an error is thrown inside render. The handler receives the Scene and the error. scene.rethrowRenderErrors controls what happens next: when false (default behavior) render returns normally after raising the event; when true the error is rethrown after the event. Keep it false in production so one bad frame does not kill the render loop.

CesiumJS does not provide rich automatic context-loss recovery. A reliable recovery is a full teardown of the Viewer followed by reconstruction.

Real Leak Versus Lost Reference

CesiumJS pools and reuses memory, so the JavaScript heap not shrinking right after a remove() is NOT proof of a leak. Confirm before chasing one:

1. Run a complete create-use-destroy cycle, then force GC in DevTools.
2. Take heap snapshots before the cycle and after GC; compare retained size.
3. If a destroyed Viewer, tileset, or your own objects are still retained, inspect the retainer chain.

The most common cause of an apparent leak is a retained JavaScript reference, not a CesiumJS bug: a closure capturing the Viewer, an array still holding removed entities, or an event listener that was never removed. Verified leak patterns and their fixes are in references/anti-patterns.md.

Common Mistakes

Reference Files

• references/methods.md : verified signatures for destroy/isDestroyed, the collection remove methods, tileset budget properties, and the context loss API.
• references/examples.md : complete teardown sequences, a React unmount pattern, and a context loss handler.
• references/anti-patterns.md : every leak and crash mode with root cause and fix.

Related Skills

• cesium-core-architecture : the Viewer / Scene / Globe hierarchy.
• cesium-core-performance : requestRenderMode and tileset LOD tuning.
• cesium-errors-memory : deeper debugging of leaks and context budget exhaustion.
• cesium-errors-rendering : blank globe and context loss diagnosis.