BabylonJS/Babylon.js · error · Error

Atmosphere is not supported on WebGL ${engine.version}.

Error message

Atmosphere is not supported on WebGL ${engine.version}.

What it means

The Atmosphere addon implements physically-based sky rendering that relies on compute-shader-like features only available on WebGPU or WebGL2. During construction it checks the engine type and version, and throws if the engine is a WebGL1 (version < 2) engine. The library intentionally refuses to run its LUT generation and rendering pipeline on engines that cannot support it.

Source

Thrown at packages/dev/addons/src/atmosphere/atmosphere.ts:678

     * Constructs the {@link Atmosphere}.
     * @param name - The name of this instance.
     * @param scene - The scene to which the atmosphere will be added.
     * @param lights - The light sources that illuminate the atmosphere. Currently only supports one light, and that light should be the first light in the scene.
     * @param options - The options used to create the atmosphere.
     */
    public constructor(
        public readonly name: string,
        public readonly scene: Scene,
        lights: DirectionalLight[],
        options?: IAtmosphereOptions
    ) {
        RegisterEngineUniformBuffer();
        RegisterEnginesExtensionsEngineRenderTarget();

        const engine = (this._engine = scene.getEngine());

        if (!engine.isWebGPU && engine.version < 2) {
            throw new Error(`Atmosphere is not supported on WebGL ${engine.version}.`);
        }

        this._physicalProperties = options?.physicalProperties ?? new AtmospherePhysicalProperties();
        this._physicalProperties.onChangedObservable.add(() => {
            this._transmittanceLut?.markDirty();
        });

        if (lights.length !== 1) {
            throw new Error("Atmosphere only supports one light source currently.");
        }
        this._lights = lights;

        this.depthTexture = options?.depthTexture ?? null;
        this._exposure = options?.exposure ?? 1.0;
        this._isLinearSpaceLight = options?.isLinearSpaceLight ?? false;
        this._isLinearSpaceComposition = options?.isLinearSpaceComposition ?? false;
        this._applyApproximateTransmittance = options?.applyApproximateTransmittance ?? true;
        this._aerialPerspectiveRadianceBias = options?.aerialPerspectiveRadianceBias ?? 0.0;

View on GitHub (pinned to 0592b347b8)

Solutions

1. Create the engine as a WebGL2 engine (new BABYLON.Engine(canvas, true) resolves to WebGL2 when available) or use WebGPUEngine via WebGPUEngine.IsSupportedAsync.
2. Check engine capability before constructing: `if (!engine.isWebGPU && engine.version < 2) { ... }` and skip/replace Atmosphere with a fallback sky (e.g. SkyMaterial or procedural sky).
3. Fix the environment so WebGL2 is available (update browser/GPU drivers, enable hardware acceleration) if WebGL1 was an unintended fallback.

Example fix

// before
const engine = new BAB.Engine(canvas, false, { webglOptions: {} }); // may end up WebGL1
const atmosphere = new Atmosphere(scene, [light]); // throws on WebGL1
// after
if (engine.isWebGPU || engine.version >= 2) {
  const atmosphere = new Atmosphere(scene, [light]);
} else {
  // fallback sky for WebGL1
  const sky = new BAB.SkyMaterial("sky", scene);
}

function canUseAtmosphere(engine: BABYLON.AbstractEngine): boolean {
  return engine.isWebGPU || engine.version >= 2;
}
if (!canUseAtmosphere(engine)) { /* use fallback sky */ }

const isAtmosphereCapable = (e: BABYLON.AbstractEngine): e is BABYLON.AbstractEngine & { version: 2 } =>
  e.isWebGPU || e.version >= 2;

try {
  atmosphere = new Atmosphere(scene, [sun]);
} catch (e) {
  if (String(e).includes("not supported on WebGL")) {
    atmosphere = null; // fall back to SkyMaterial
  } else throw e;
}

When it happens

Trigger: Calling `new Atmosphere(scene, lights, options)` (or creating it via any helper) while the scene's engine is a WebGL1 engine, i.e. `engine.isWebGPU === false && engine.version < 2`.

Common situations: Projects still targeting WebGL1 for legacy browser/device support, using `Engine` (not `WebGL2Engine`/`WebGPUEngine`) on a context that fell back to WebGL1, or old environments (e.g. older Safari/iOS) where WebGL2 is unavailable and the engine falls back.

Related errors

• Atmosphere only supports one light source currently.
• Depth texture is required for aerial perspective compositor.
• Sample2DRgbaToRef: widthPx and heightPx must be positive.
• Sample2DRgbaToRef: data length (${data.length}) is less than
• Failed to get client rect for rendering canvas

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/6f2fb22b8fa8fc92. Report an issue: GitHub.