BabylonJS/Babylon.js · critical · Error

WebGL not supported

Error message

WebGL not supported

What it means

Thrown when the canvas is valid but canvas.getContext('webgl') / ('experimental-webgl') returned null — the browser (or environment) cannot provide a WebGL 1 context. The engine has no rendering backend and cannot initialize.

Source

Thrown at packages/dev/core/src/Engines/thinEngine.pure.ts:388

                        // Prevent weird browsers to lie (yeah that happens!)
                        if (!this._gl.deleteQuery) {
                            this._webGLVersion = 1.0;
                            this._shaderPlatformName = "WEBGL1";
                        }
                    }
                } catch (e) {
                    // Do nothing
                }
            }

            if (!this._gl) {
                if (!canvas) {
                    throw new Error("The provided canvas is null or undefined.");
                }
                try {
                    this._gl = <WebGL2RenderingContext>(canvas.getContext("webgl", options) || canvas.getContext("experimental-webgl", options));
                } catch (e) {
                    throw new Error("WebGL not supported", { cause: e });
                }
            }

            if (!this._gl) {
                throw new Error("WebGL not supported");
            }
        } else {
            this._gl = <WebGL2RenderingContext>canvasOrContext;
            canvas = this._gl.canvas as HTMLCanvasElement;

            if ((this._gl as any).renderbufferStorageMultisample) {
                this._webGLVersion = 2.0;
                this._shaderPlatformName = "WEBGL2";
            } else {
                this._shaderPlatformName = "WEBGL1";
            }

            const attributes = this._gl.getContextAttributes();

View on GitHub (pinned to 0592b347b8)

Solutions

1. Enable hardware acceleration / WebGL in browser settings (chrome://gpu to verify)
2. Run tests with a software GL backend (SwiftShader / --use-gl=swiftshader flags in headless Chrome)
3. Verify the canvas hasn't already acquired a different context type ('2d') — each canvas supports one context type
4. Show a user-facing fallback (message or 2D rendering) when WebGL is unavailable

Example fix

// before
const engine = new Engine(canvas, true); // crashes on machines without WebGL
// after
const testCanvas = document.createElement('canvas');
if (!testCanvas.getContext('webgl')) { showWebGLFallback(); } else { const engine = new Engine(canvas, true); }

export function isWebGLSupported(): boolean {
  try {
    const c = document.createElement('canvas');
    return !!(c.getContext('webgl') || c.getContext('experimental-webgl'));
  } catch { return false; }
}

null

try {
  const engine = new Engine(canvas, true);
} catch (e) {
  if ((e as Error).message === 'WebGL not supported') {
    renderFallbackUI(); // 2D canvas or message
  } else throw e;
}

When it happens

Trigger: Calling getContext on a canvas in an environment without WebGL support: headless browsers without GPU/swiftshader, browsers with WebGL disabled in settings, GPU blocklisted by the browser, or getContext throwing/returning null under hardware-acceleration-disabled configurations.

Common situations: CI/headless testing environments without GPU; corporate machines with hardware acceleration disabled; old browsers or VMs without GPU drivers; canvas already used with a '2d' context (different context type requested earlier on the same canvas).

Related errors

• DumpData: No WebGL context available. Cannot dump data.
• Atmosphere is not supported on WebGL ${engine.version}.
• Instanced arrays are required for MSDF text rendering.
• Unable to create multi sampled framebuffer
• Invalid Space Warp framebuffer

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