Cesium Errors Rendering

CesiumJS Rendering Errors

Overview

A CesiumJS rendering failure is a configuration or lifecycle fault, not a CesiumJS bug. Failures take three shapes, and each shape has one root-cause family:

1. The globe never appears (blank, black, or white at load) : static assets are unreachable, or the Cesium ion token is missing.
2. The globe appears and then dies (black or frozen mid-session) : the WebGL context was lost, or the per-tab context budget is exhausted.
3. An error panel covers the canvas : an exception was thrown inside Scene.render.

This skill maps every symptom to its single root cause and a deterministic fix. ALWAYS diagnose from the browser Console before changing code.

When to Use

Use this skill when:

• The CesiumJS canvas element exists but the globe is blank, black, or white.
• The Console shows HTTP 404 for Workers/, Assets/, or Widgets/ files.
• The Network tab shows HTTP 401 from api.cesium.com or assets.cesium.com.
• The globe freezes or turns black mid-session with CONTEXT_LOST_WEBGL.
• The Console reports Too many active WebGL contexts.
• An "An error occurred while rendering" panel appears over the canvas.
• The globe renders but has no map imagery, or no terrain relief.

Do NOT use this skill when:

• A 3D Tileset fails with CORS, 401, 403, or 404 : use cesium-errors-tileset.
• Memory grows over time or destroy() ordering is wrong : use cesium-errors-memory.
• Positions are NaN or geometry sits off the globe : use cesium-errors-coordinates.

Step Zero : Read the Console

ALWAYS open browser devtools and read the Console and Network tabs BEFORE editing code. The console signal names the root cause. Guessing wastes time and hides the real fault.

Quick Reference : The 8 Rendering Errors

Full entries with symptom, root cause, prevention, and recovery are in references/anti-patterns.md.

Decision Tree : Blank or Black Globe

Globe never appeared (blank, black, or white at load)
├─ Console: 404 for Workers/ Assets/ Widgets/
│   ├─ 404 in dev AND prod      -> E1  CESIUM_BASE_URL unset or wrong
│   └─ 404 in prod build only   -> E2  bundler asset-copy omitted
├─ Network: 401 from *.cesium.com -> E3  ion token missing or invalid
└─ No 404, no 401
    ├─ globe is a flat solid color    -> E7  no imagery layer
    └─ globe surface is a smooth ball -> E8  no terrain provider

Globe appeared, then died (black or frozen mid-session)
├─ Console: CONTEXT_LOST_WEBGL              -> E4  WebGL context lost
└─ Console: Too many active WebGL contexts  -> E5  context budget exhausted

Error panel covers the canvas
└─ "An error occurred while rendering"      -> E6  exception in Scene.render

Correct Bootstrap Sequence

The order is fixed. A correct CesiumJS start ALWAYS runs these steps in this sequence:

1. Set window.CESIUM_BASE_URL, OR let the bundler plugin define it, BEFORE importing cesium.
2. Import cesium.
3. Set Cesium.Ion.defaultAccessToken, only when an ion asset is used.
4. Construct new Cesium.Viewer(container, options).
5. await async factories (terrain, tilesets, imagery) inside try/catch.
6. Add data sources, then move the camera.

// main.js
window.CESIUM_BASE_URL = "/cesium/"; // step 1 : before the import

import * as Cesium from "cesium";    // step 2
import "cesium/Build/Cesium/Widgets/widgets.css";

Cesium.Ion.defaultAccessToken = import.meta.env.VITE_CESIUM_ION_TOKEN; // step 3

const viewer = new Cesium.Viewer("cesiumContainer", {  // step 4
  terrain: Cesium.Terrain.fromWorldTerrain(),
});

Skipping step 1 or step 3 is the dominant cause of a blank globe. The full verified example is in references/examples.md.

Context Loss : Recovery Is Recreation

CesiumJS does NOT restore GPU resources after a lost WebGL context. The recovery path is recreation, not repair:

1. Listen for webglcontextlost on viewer.scene.canvas and call event.preventDefault() so the browser keeps the canvas restorable.
2. On webglcontextrestored, call viewer.destroy() on the dead viewer and construct a fresh Viewer.

Reducing GPU load (lower maximumScreenSpaceError, lower cacheBytes, lower resolutionScale) prevents the loss on memory-constrained devices. See references/examples.md for the handler.

ALWAYS / NEVER

• ALWAYS set window.CESIUM_BASE_URL, or define it through the bundler plugin, before the cesium import resolves. CesiumJS fetches Web Workers, assets, and widget CSS from that URL at runtime.
• ALWAYS set Cesium.Ion.defaultAccessToken before constructing a Viewer that uses any ion asset (World Terrain, OSM Buildings, ion imagery).
• ALWAYS pass baseLayer: false when the application has no ion token, then supply a non-ion imagery provider. NEVER leave the default ion base layer in place without a valid token.
• ALWAYS call viewer.destroy() when a Viewer leaves the page. NEVER create a Viewer per route or per component without destroying the previous one.
• ALWAYS subscribe to scene.renderError so a render-loop exception is logged instead of silently producing a frozen frame.
• ALWAYS call event.preventDefault() inside the webglcontextlost handler.
• NEVER assume viewer.destroy() frees the WebGL context immediately; the browser caps live contexts near 16 per tab. Reuse one Viewer where the app allows it.
• NEVER reference a WebGPU rendering path. CesiumJS renders exclusively on WebGL2 through the 1.142 line.
• NEVER use readyPromise, .ready, new Cesium3DTileset({url}), ModelExperimental, or defaultValue(). They were removed; use the async factories and the ?? operator.

Common Mistakes

Reference Files

• references/methods.md : verified APIs for diagnosis and recovery (CESIUM_BASE_URL, Ion.defaultAccessToken, Scene.renderError, rethrowRenderErrors, errorEvent, Terrain.fromWorldTerrain, build plugins).
• references/examples.md : verified working code (correct bootstrap, render error handler, context-loss recovery, Vite and webpack config, imagery and terrain fallback, single-viewer reuse).
• references/anti-patterns.md : the 8 rendering errors, each with symptom, root cause, prevention, and recovery.