phaserjs/phaser · critical · Error

ANGLE_instanced_arrays extension not supported. Required for

Error message

ANGLE_instanced_arrays extension not supported. Required for rendering.

What it means

WebGLRenderer.js:909 throws during WebGL1 extension incorporation when `this.instancedArraysExtension` (ANGLE_instanced_arrays) is null. Phaser's WebGL1 renderer requires hardware instancing to batch sprites/particles; without it the renderer cannot be built. The branch only runs when `gl instanceof WebGLRenderingContext` (WebGL1) — WebGL2 provides instancing natively.

Source

Thrown at src/renderer/webgl/WebGLRenderer.js:909

        var stdDerivativesString = 'OES_standard_derivatives';

        this.standardDerivativesExtension = (exts.indexOf(stdDerivativesString) > -1) ? gl.getExtension(stdDerivativesString) : null;

        // Make WebGL2 core features which were extensions available on the WebGL1 context.
        // This allows us to use a WebGL2 context.
        if (gl instanceof WebGLRenderingContext)
        {
            // Incorporate instanced arrays.
            if (this.instancedArraysExtension)
            {
                gl.vertexAttribDivisor = this.instancedArraysExtension.vertexAttribDivisorANGLE.bind(this.instancedArraysExtension);
                gl.drawArraysInstanced = this.instancedArraysExtension.drawArraysInstancedANGLE.bind(this.instancedArraysExtension);
                gl.drawElementsInstanced = this.instancedArraysExtension.drawElementsInstancedANGLE.bind(this.instancedArraysExtension);
            }
            else
            {
                throw new Error('ANGLE_instanced_arrays extension not supported. Required for rendering.');
            }

            // Incorporate vertex array objects.
            if (this.vaoExtension)
            {
                gl.createVertexArray = this.vaoExtension.createVertexArrayOES.bind(this.vaoExtension);
                gl.bindVertexArray = this.vaoExtension.bindVertexArrayOES.bind(this.vaoExtension);
                gl.deleteVertexArray = this.vaoExtension.deleteVertexArrayOES.bind(this.vaoExtension);
                gl.isVertexArray = this.vaoExtension.isVertexArrayOES.bind(this.vaoExtension);
            }
            else
            {
                throw new Error('OES_vertex_array_object extension not supported. Required for rendering.');
            }

            // Incorporate standard derivatives.
            if (this.standardDerivativesExtension)
            {

View on GitHub (pinned to 41be1e462b)

Solutions

Force a WebGL2 context where possible (newer Phaser builds prefer WebGL2 if available) — ensure the browser/device supports it.
Upgrade the target device/browser to one that exposes ANGLE_instanced_arrays or WebGL2.
Accept the device is unsupported by Phaser's WebGL renderer and fall back to `type: Phaser.CANVAS`.

Example fix

// before (WebGL1 device without ANGLE_instanced_arrays)
type: Phaser.WEBGL
// after
type: Phaser.AUTO // or Phaser.CANVAS on that device

Defensive patterns

Strategy: fallback

Validate before calling

const c = document.createElement('canvas')
const gl2 = c.getContext('webgl2')
let type
if (gl2) {
  type = Phaser.WEBGL // WebGL2 has instancing built in
} else {
  const gl1 = c.getContext('webgl')
  const hasInstancing = gl1 && gl1.getExtension('ANGLE_instanced_arrays')
  type = hasInstancing ? Phaser.WEBGL : Phaser.CANVAS
}
const game = new Phaser.Game({ type, width: 800, height: 600 })

Type guard

const webgl1HasInstancing = () => {
  const c = document.createElement('canvas')
  const gl = c.getContext('webgl')
  return !!gl && !!gl.getExtension('ANGLE_instanced_arrays')
}

Try / catch

try {
  game = new Phaser.Game({ type: Phaser.WEBGL, ... })
} catch (e) {
  if (/ANGLE_instanced_arrays/.test(e.message)) {
    game = new Phaser.Game({ type: Phaser.CANVAS, ... })
  } else { throw e }
}

Prevention

Prefer WebGL2 contexts to bypass the WebGL1 extension requirements.
Detect instancing support before committing to WEBGL and fall back to CANVAS.
Document minimum device requirements if WebGL is mandatory.

When it happens

Trigger: Running on a WebGL1-only context where the ANGLE_instanced_arrays extension is unavailable or disabled. WebGL2 contexts skip this branch entirely, so this is effectively a legacy/old-device failure.

Common situations: Very old mobile devices or GPUs that expose WebGL1 but not the ANGLE instancing extension; browsers/drivers that disable optional WebGL1 extensions; test environments pinned to WebGL1.

Related errors

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