{"record":{"id":"09ae7d8233bacccd","repo":"phaserjs/phaser","slug":"cannot-create-canvas-context-aborting","errorCode":null,"errorMessage":"Cannot create Canvas context, aborting.","messagePattern":"Cannot create Canvas context, aborting\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/core/CreateRenderer.js","lineNumber":53,"sourceCode":"    {\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;\n\n    var width = baseSize.width;\n    var height = baseSize.height;\n","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/core/CreateRenderer.js#L35-L71","documentation":"CreateRenderer.js:53 is the Canvas mirror of the WebGL check: you set `renderType === CANVAS` but `Features.canvas` is false, so a 2D context is unavailable. Phaser throws rather than silently no-op a renderer you explicitly requested.","triggerScenarios":"`type: Phaser.CANVAS` in an environment where `document.createElement('canvas').getContext('2d')` returned null/undefined: jsdom, a worker context, or a locked-down environment. Rare in real browsers but common in Node-based test setups.","commonSituations":"Unit tests under jsdom (which lacks a real canvas implementation), server-side rendering, or running Phaser inside a Web Worker without OffscreenCanvas wiring.","solutions":["Use `type: Phaser.AUTO` to let Phaser pick WebGL if Canvas is missing.","Use `type: Phaser.HEADLESS` for non-visual/test runs.","Install a canvas polyfill (e.g. `canvas` npm package + jsdom) if you truly need a 2D context under Node."],"exampleFix":"// before\ntype: Phaser.CANVAS // under jsdom\n// after\ntype: Phaser.HEADLESS","handlingStrategy":"validation","validationCode":"const type = Phaser.DEVICE.features.canvas ? Phaser.CANVAS : Phaser.HEADLESS\nconst game = new Phaser.Game({ type, width: 800, height: 600 })","typeGuard":"const supportsCanvas2D = () => {\n  try { return !!document.createElement('canvas').getContext('2d') } catch { return false }\n}","tryCatchPattern":null,"preventionTips":["Avoid Phaser.CANVAS in Node/jsdom without a canvas polyfill.","Use Phaser.HEADLESS for non-visual/test runs.","Prefer Phaser.AUTO so Phaser falls back to WebGL if Canvas is absent."],"tags":["renderer","canvas","environment","startup"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}