{"record":{"id":"d63927de3951934d","repo":"BabylonJS/Babylon.js","slug":"webgl-not-supported","errorCode":null,"errorMessage":"WebGL not supported","messagePattern":"WebGL not supported","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/dev/core/src/Engines/thinEngine.pure.ts","lineNumber":388,"sourceCode":"                        // Prevent weird browsers to lie (yeah that happens!)\r\n                        if (!this._gl.deleteQuery) {\r\n                            this._webGLVersion = 1.0;\r\n                            this._shaderPlatformName = \"WEBGL1\";\r\n                        }\r\n                    }\r\n                } catch (e) {\r\n                    // Do nothing\r\n                }\r\n            }\r\n\r\n            if (!this._gl) {\r\n                if (!canvas) {\r\n                    throw new Error(\"The provided canvas is null or undefined.\");\r\n                }\r\n                try {\r\n                    this._gl = <WebGL2RenderingContext>(canvas.getContext(\"webgl\", options) || canvas.getContext(\"experimental-webgl\", options));\r\n                } catch (e) {\r\n                    throw new Error(\"WebGL not supported\", { cause: e });\r\n                }\r\n            }\r\n\r\n            if (!this._gl) {\r\n                throw new Error(\"WebGL not supported\");\r\n            }\r\n        } else {\r\n            this._gl = <WebGL2RenderingContext>canvasOrContext;\r\n            canvas = this._gl.canvas as HTMLCanvasElement;\r\n\r\n            if ((this._gl as any).renderbufferStorageMultisample) {\r\n                this._webGLVersion = 2.0;\r\n                this._shaderPlatformName = \"WEBGL2\";\r\n            } else {\r\n                this._shaderPlatformName = \"WEBGL1\";\r\n            }\r\n\r\n            const attributes = this._gl.getContextAttributes();\r","sourceCodeStart":370,"sourceCodeEnd":406,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Engines/thinEngine.pure.ts#L370-L406","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Enable hardware acceleration / WebGL in browser settings (chrome://gpu to verify)","Run tests with a software GL backend (SwiftShader / --use-gl=swiftshader flags in headless Chrome)","Verify the canvas hasn't already acquired a different context type ('2d') — each canvas supports one context type","Show a user-facing fallback (message or 2D rendering) when WebGL is unavailable"],"exampleFix":"// before\nconst engine = new Engine(canvas, true); // crashes on machines without WebGL\n// after\nconst testCanvas = document.createElement('canvas');\nif (!testCanvas.getContext('webgl')) { showWebGLFallback(); } else { const engine = new Engine(canvas, true); }","handlingStrategy":"fallback","validationCode":"export function isWebGLSupported(): boolean {\n  try {\n    const c = document.createElement('canvas');\n    return !!(c.getContext('webgl') || c.getContext('experimental-webgl'));\n  } catch { return false; }\n}","typeGuard":"null","tryCatchPattern":"try {\n  const engine = new Engine(canvas, true);\n} catch (e) {\n  if ((e as Error).message === 'WebGL not supported') {\n    renderFallbackUI(); // 2D canvas or message\n  } else throw e;\n}","preventionTips":["Feature-detect WebGL before app bootstrap and show a support notice early","Check chrome://gpu / browser flags when it fails on a specific machine","In headless CI, enable SwiftShader (--enable-unsafe-swiftshader / --use-gl=angle)","Never call canvas.getContext('2d') before requesting the webgl context on the same canvas"],"tags":["webgl","browser-compatibility","environment"],"backgroundTag":"webgl-unsupported","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}