{"record":{"id":"3ffb233f88e2858b","repo":"phaserjs/phaser","slug":"must-set-explicit-rendertype-in-custom-environment","errorCode":null,"errorMessage":"Must set explicit renderType in custom environment","messagePattern":"Must set explicit renderType in custom environment","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/core/CreateRenderer.js","lineNumber":36,"sourceCode":" * any canvas CSS styles and pixel art interpolation settings, then instantiates and assigns the renderer\n * to `game.renderer`.\n *\n * Relies upon two webpack global flags, `WEBGL_RENDERER` and `CANVAS_RENDERER`, which are defined at\n * build time and inlined into the bundle as compile-time constants. They are not available as runtime\n * variables and determine which renderer classes are included in the build.\n *\n * @function Phaser.Core.CreateRenderer\n * @since 3.0.0\n *\n * @param {Phaser.Game} game - The Phaser.Game instance on which the renderer will be set.\n */\nvar CreateRenderer = function (game)\n{\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        }","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/core/CreateRenderer.js#L18-L54","documentation":"Phaser's renderer auto-detection (AUTO -> WebGL or Canvas) relies on probing the host environment at runtime. When you opt out of that probing by setting `customEnvironment: true` or by passing your own `canvas`, Phaser refuses to guess a renderer and demands an explicit `renderType`. The check lives in CreateRenderer.js:34 and fires only when `renderType === CONST.AUTO` is combined with a custom environment/own canvas.","triggerScenarios":"Passing `new Phaser.Game({ customEnvironment: true })` (or `canvas: myCanvas`) while leaving the default `type: Phaser.AUTO` (the value of `Phaser.AUTO`). AUTO is numeric 1; the guard triggers on the AUTO branch regardless of host capabilities.","commonSituations":"Running Phaser in Electron/offscreen, NW.js, jsdom/headless test harnesses (Jest, Mocha), or server-side render farms where feature detection is unreliable or unwanted. Developers copy a minimal config and forget to pin the renderer.","solutions":["Set an explicit renderer type in the game config, e.g. `type: Phaser.WEBGL` (or `Phaser.CANVAS`, or `Phaser.HEADLESS` for non-visual servers).","If you genuinely want auto-detection, remove `customEnvironment: true` and do not pass your own `canvas` — let Phaser create one.","For headless servers/tests use `type: Phaser.HEADLESS` so no context creation is attempted."],"exampleFix":"// before\nnew Phaser.Game({ customEnvironment: true, width: 800, height: 600 })\n// after\nnew Phaser.Game({ customEnvironment: true, type: Phaser.CANVAS, width: 800, height: 600 })","handlingStrategy":"validation","validationCode":"const cfg = { customEnvironment: true, /* ... */ }\nconst AUTO = Phaser.AUTO // numeric constant\nif ((cfg.customEnvironment || cfg.canvas) && cfg.type === AUTO) {\n  throw new Error('Config error: set an explicit type (Phaser.WEBGL/CANVAS/HEADLESS) when using customEnvironment/canvas')\n}\nconst game = new Phaser.Game(cfg)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pin `type` to a concrete renderer constant when setting `customEnvironment` or `canvas`.","Centralise game config construction in one module so the customEnvironment+type rule is checked in one place.","Write a unit test asserting the config object never pairs customEnvironment with AUTO."],"tags":["config","renderer","custom-environment","startup"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}