phaserjs/phaser · error · Error

Cannot create WebGL context, aborting.

Error message

Cannot create WebGL context, aborting.

What it means

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.

Source

Thrown at src/core/CreateRenderer.js:49

{
    var config = game.config;

    if ((config.customEnvironment || config.canvas) && config.renderType === CONST.AUTO)
    {
        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;

View on GitHub (pinned to 41be1e462b)

Solutions

1. Switch the config to `type: Phaser.AUTO` so Phaser falls back to Canvas when WebGL is unavailable.
2. Provide a Canvas fallback in app code: detect `Phaser.Device.os`/feature support before constructing the game.
3. For headless/CI runs use `type: Phaser.HEADLESS` instead.
4. Enable WebGL in the test browser (e.g. Chrome `--use-gl=angle --use-angle=swiftshader`, or Xvfb with a GL driver).

Example fix

// before
type: Phaser.WEBGL
// after
type: Phaser.AUTO // Phaser.WebGL if available, else Canvas

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

// Phaser.Feature / Phaser.Device is not a class; use the device flags
const supportsWebGL = () => {
  try {
    const c = document.createElement('canvas')
    return !!(c.getContext('webgl') || c.getContext('experimental-webgl'))
  } catch { return false }
}

When it happens

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

Common situations: 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`.

Related errors

• WebGL unsupported
• Cannot create Canvas context, aborting.
• Must set explicit renderType in custom environment
• Unknown value for renderer type:
• ANGLE_instanced_arrays extension not supported. Required for

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