{"record":{"id":"c83591c48894c8e9","repo":"phaserjs/phaser","slug":"cannot-create-webgl-context-aborting","errorCode":null,"errorMessage":"Cannot create WebGL context, aborting.","messagePattern":"Cannot create WebGL context, aborting\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/core/CreateRenderer.js","lineNumber":49,"sourceCode":"{\n    var config = game.config;\n\n    if ((config.customEnvironment || config.canvas) && config.renderType === CONST.AUTO)\n    {\n        throw new Error('Must set explicit renderType in custom environment');\n    }\n\n    //  Not a custom environment, didn't provide their own canvas and not headless, so determine the renderer:\n    if (!config.customEnvironment && !config.canvas && config.renderType !== CONST.HEADLESS)\n    {\n        if (config.renderType === CONST.AUTO)\n        {\n            config.renderType = Features.webGL ? CONST.WEBGL : CONST.CANVAS;\n        }\n\n        if (config.renderType === CONST.WEBGL)\n        {\n            if (!Features.webGL) { throw new Error('Cannot create WebGL context, aborting.'); }\n        }\n        else if (config.renderType === CONST.CANVAS)\n        {\n            if (!Features.canvas) { throw new Error('Cannot create Canvas context, aborting.'); }\n        }\n        else\n        {\n            throw new Error('Unknown value for renderer type: ' + config.renderType);\n        }\n    }\n\n    //  Pixel Art mode?\n    if (!config.antialias)\n    {\n        CanvasPool.disableSmoothing();\n    }\n\n    var baseSize = game.scale.baseSize;","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/core/CreateRenderer.js#L31-L67","documentation":"CreateRenderer.js:49 throws when you explicitly request WebGL (`renderType === WEBGL`) but Phaser's `Features.webGL` check returned false, meaning no usable WebGLRenderingContext could be detected in the host. Phaser refuses to silently downgrade because you asked specifically for WebGL.","triggerScenarios":"Configuring `type: Phaser.WEBGL` in an environment without WebGL: software-rendered browsers, disabled GPU acceleration (some VMs/RDP), very old mobile browsers, headless browsers without `--use-gl=swiftshader`, or jsdom. Also when `customEnvironment` was set with a feature-check that cleared `Features.webGL`.","commonSituations":"CI headless Chrome without GPU flags; corporate VMs with GPU blocklisted by the browser; older iOS Safari versions; the `webgl` context being lost or blacklisted by `about:gpu`.","solutions":["Switch the config to `type: Phaser.AUTO` so Phaser falls back to Canvas when WebGL is unavailable.","Provide a Canvas fallback in app code: detect `Phaser.Device.os`/feature support before constructing the game.","For headless/CI runs use `type: Phaser.HEADLESS` instead.","Enable WebGL in the test browser (e.g. Chrome `--use-gl=angle --use-angle=swiftshader`, or Xvfb with a GL driver)."],"exampleFix":"// before\ntype: Phaser.WEBGL\n// after\ntype: Phaser.AUTO // Phaser.WebGL if available, else Canvas","handlingStrategy":"validation","validationCode":"const type = Phaser.DEVICE.features.webGL ? Phaser.WEBGL : Phaser.CANVAS\nconst game = new Phaser.Game({ type, width: 800, height: 600 })","typeGuard":"// Phaser.Feature / Phaser.Device is not a class; use the device flags\nconst supportsWebGL = () => {\n  try {\n    const c = document.createElement('canvas')\n    return !!(c.getContext('webgl') || c.getContext('experimental-webgl'))\n  } catch { return false }\n}","tryCatchPattern":null,"preventionTips":["Use Phaser.AUTO unless you have a hard reason to require WebGL.","For CI/headless, launch Chrome with a software GL flag or use HEADLESS.","Detect WebGL once at app boot and pass the resolved type into the config."],"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"}