phaserjs/phaser · error · Error

Cannot create Canvas context, aborting.

Error message

Cannot create Canvas context, aborting.

What it means

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.

Source

Thrown at src/core/CreateRenderer.js:53

    {
        throw new Error('Must set explicit renderType in custom environment');
    }

    //  Not a custom environment, didn't provide their own canvas and not headless, so determine the renderer:
    if (!config.customEnvironment && !config.canvas && config.renderType !== CONST.HEADLESS)
    {
        if (config.renderType === CONST.AUTO)
        {
            config.renderType = Features.webGL ? CONST.WEBGL : CONST.CANVAS;
        }

        if (config.renderType === CONST.WEBGL)
        {
            if (!Features.webGL) { throw new Error('Cannot create WebGL context, aborting.'); }
        }
        else if (config.renderType === CONST.CANVAS)
        {
            if (!Features.canvas) { throw new Error('Cannot create Canvas context, aborting.'); }
        }
        else
        {
            throw new Error('Unknown value for renderer type: ' + config.renderType);
        }
    }

    //  Pixel Art mode?
    if (!config.antialias)
    {
        CanvasPool.disableSmoothing();
    }

    var baseSize = game.scale.baseSize;

    var width = baseSize.width;
    var height = baseSize.height;

View on GitHub (pinned to 41be1e462b)

Solutions

1. Use `type: Phaser.AUTO` to let Phaser pick WebGL if Canvas is missing.
2. Use `type: Phaser.HEADLESS` for non-visual/test runs.
3. Install a canvas polyfill (e.g. `canvas` npm package + jsdom) if you truly need a 2D context under Node.

Example fix

// before
type: Phaser.CANVAS // under jsdom
// after
type: Phaser.HEADLESS

const type = Phaser.DEVICE.features.canvas ? Phaser.CANVAS : Phaser.HEADLESS
const game = new Phaser.Game({ type, width: 800, height: 600 })

const supportsCanvas2D = () => {
  try { return !!document.createElement('canvas').getContext('2d') } catch { return false }
}

When it happens

Trigger: `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.

Common situations: Unit tests under jsdom (which lacks a real canvas implementation), server-side rendering, or running Phaser inside a Web Worker without OffscreenCanvas wiring.

Related errors

• Cannot create WebGL context, aborting.
• WebGL unsupported
• Must set explicit renderType in custom environment
• Unknown value for renderer type:
• No DOM Container set in game config

AI-assisted analysis of phaserjs/phaser@41be1e462b (2026-08-13). Data as JSON: /api/errors/09ae7d8233bacccd. Report an issue: GitHub.