{"record":{"id":"c8f66d2e4ad2dd55","repo":"phaserjs/phaser","slug":"webgl-unsupported","errorCode":null,"errorMessage":"WebGL unsupported","messagePattern":"WebGL unsupported","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/renderer/webgl/WebGLRenderer.js","lineNumber":716,"sourceCode":"\n            this.spector.onCapture.add(this.onCapture.bind(this));\n        }\n\n        //  Did they provide their own context?\n        if (game.config.context)\n        {\n            gl = game.config.context;\n        }\n        else\n        {\n            gl = canvas.getContext('webgl', config.contextCreation) || canvas.getContext('experimental-webgl', config.contextCreation);\n        }\n\n        if (!gl || gl.isContextLost())\n        {\n            this.contextLost = true;\n\n            throw new Error('WebGL unsupported');\n        }\n\n        this.gl = gl;\n\n        this.setExtensions();\n\n        this.setContextHandlers();\n\n        //  Set it back into the Game, so developers can access it from there too\n        game.context = gl;\n\n        for (var i = 0; i <= 27; i++)\n        {\n            this.blendModes.push(WebGLBlendParametersFactory.createCombined(this));\n        }\n\n        //  ADD\n        this.blendModes[1].func = [ gl.ONE, gl.DST_ALPHA, gl.ONE, gl.DST_ALPHA ];","sourceCodeStart":698,"sourceCodeEnd":734,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/renderer/webgl/WebGLRenderer.js#L698-L734","documentation":"WebGLRenderer.js:716 throws after both `getContext('webgl', ...)` and the `experimental-webgl` fallback return null (or a freshly-lost context). The renderer cannot function without a GL context, so it marks `contextLost = true` and aborts construction.","triggerScenarios":"Constructing a WebGLRenderer (via `type: Phaser.WEBGL` or AUTO-resolved-to-WebGL) where the canvas yields no GL context: GPU blacklisted by the browser, driver crash, disabled WebGL, or an environment without WebGL support. The `game.config.context` branch (a developer-supplied context) only bypasses this if non-null and not lost.","commonSituations":"CI/headless browsers without GPU; locked-down corporate machines where WebGL is disabled in about:flags; older mobile GPUs on the driver blocklist; the user disabled hardware acceleration in their browser settings.","solutions":["Fall back to Canvas: set `type: Phaser.AUTO` (Phaser picks Canvas when WebGL probe fails) or explicitly `Phaser.CANVAS`.","For headless/CI, run with a software GL backend (Chrome `--use-gl=angle --use-angle=swiftshader-webgl`, or Xvfb + Mesa).","Prompt the user to enable WebGL/hardware acceleration in their browser.","Provide a `contextLostHandler` for graceful runtime recovery if the context dies later."],"exampleFix":"// before\ntype: Phaser.WEBGL // fails on GPU-less host\n// after\ntype: Phaser.AUTO","handlingStrategy":"fallback","validationCode":"let gl\ntry {\n  const c = document.createElement('canvas')\n  gl = c.getContext('webgl') || c.getContext('experimental-webgl')\n} catch { gl = null }\nconst type = gl ? Phaser.WEBGL : Phaser.CANVAS\nconst game = new Phaser.Game({ type, width: 800, height: 600 })","typeGuard":"const getContextOrThrow = () => {\n  const c = document.createElement('canvas')\n  const gl = c.getContext('webgl') || c.getContext('experimental-webgl')\n  if (!gl || gl.isContextLost()) throw new Error('WebGL unsupported')\n  return gl\n}","tryCatchPattern":"try {\n  game = new Phaser.Game({ type: Phaser.WEBGL, ... })\n} catch (e) {\n  if (/WebGL unsupported/.test(e.message)) {\n    game = new Phaser.Game({ type: Phaser.CANVAS, ... })\n  } else { throw e }\n}","preventionTips":["Use Phaser.AUTO so Phaser falls back to Canvas when no GL context exists.","For CI/headless, run a software GL backend (swiftshader/Mesa).","Set contextLostHandler/contextRestoredHandler for runtime recovery.","Show a user-facing message and fall back when construction throws."],"tags":["renderer","webgl","environment","startup"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}