phaserjs/phaser · critical · Error

OES_vertex_array_object extension not supported. Required fo

Error message

OES_vertex_array_object extension not supported. Required for rendering.

What it means

WebGLRenderer.js:922 throws when the OES_vertex_array_object extension is missing under a WebGL1 context. Like the instancing extension, VAOs are required by Phaser's WebGL1 batching pipeline to manage vertex attribute bindings efficiently. WebGL2 provides VAOs natively, so the branch is skipped there.

Source

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

                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)
            {
                gl.FRAGMENT_SHADER_DERIVATIVE_HINT = this.standardDerivativesExtension.FRAGMENT_SHADER_DERIVATIVE_HINT_OES;
            }
            else if (game.config.smoothPixelArt)
            {
                throw new Error('OES_standard_derivatives extension not supported. Cannot use smoothPixelArt.');
            }
        }
    },

    /**
     * Sets the handlers that are called when WebGL context is lost or restored by the browser.
     *
     * The default handlers are referenced via the properties `WebGLRenderer.contextLostHandler` and `WebGLRenderer.contextRestoredHandler`.

View on GitHub (pinned to 41be1e462b)

Solutions

1. Prefer a WebGL2 context (ensure device/browser support WebGL2, which bundles VAOs).
2. Fall back to Canvas rendering (`type: Phaser.AUTO` or `Phaser.CANVAS`).
3. Treat the device as unsupported for the WebGL renderer.

Example fix

// before
type: Phaser.WEBGL // WebGL1 without OES_vertex_array_object
// after
type: Phaser.CANVAS

const c = document.createElement('canvas')
const gl2 = c.getContext('webgl2')
let type
if (gl2) {
  type = Phaser.WEBGL
} else {
  const gl1 = c.getContext('webgl')
  const hasVAO = gl1 && gl1.getExtension('OES_vertex_array_object')
  type = hasVAO ? Phaser.WEBGL : Phaser.CANVAS
}
const game = new Phaser.Game({ type, width: 800, height: 600 })

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

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

When it happens

Trigger: A WebGL1-only context that does not expose OES_vertex_array_object. Same family as error 17; occurs during `setExtensions`/context setup in the WebGL1 code path.

Common situations: Old mobile GPUs/drivers with incomplete WebGL1 extension support; embedded/legacy devices; some software rasterizers that expose only a subset of WebGL1 extensions.

Related errors

• ANGLE_instanced_arrays extension not supported. Required for
• OES_standard_derivatives extension not supported. Cannot use
• Cannot create WebGL context, aborting.
• WebGL unsupported
• BatchHandler must have a name

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