phaserjs/phaser · error · Error

OES_standard_derivatives extension not supported. Cannot use

Error message

OES_standard_derivatives extension not supported. Cannot use smoothPixelArt.

What it means

WebGLRenderer.js:932 throws only when `game.config.smoothPixelArt` is true AND `this.standardDerivativesExtension` (OES_standard_derivatives) is unavailable under WebGL1. Unlike errors 17/18 this extension is optional — Phaser only demands it when the user explicitly enabled the smooth-pixel-art shader feature, which needs derivative hints.

Source

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

            {
                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`.
     * By default, these map to the methods `WebGLRenderer.dispatchContextLost` and `WebGLRenderer.dispatchContextRestored`.
     *
     * You can override these handlers with your own via this method.
     *
     * If you do override them, make sure that your handlers invoke the methods `WebGLRenderer.dispatchContextLost` and `WebGLRenderer.dispatchContextRestored` in due course, otherwise the renderer will not be able to restore itself fully.
     *
     * @method Phaser.Renderer.WebGL.WebGLRenderer#setContextHandlers
     * @since 3.85.0
     *
     * @param {function} [contextLost] - Custom handler for responding to the WebGL context lost event. Set as `undefined` to use the default handler.

View on GitHub (pinned to 41be1e462b)

Solutions

1. Disable `smoothPixelArt` in the config (use `pixelArt: true` / `antialias: false` instead for blocky pixel rendering).
2. Move to a WebGL2-capable device/browser where derivatives are core.
3. Keep smoothPixelArt only when you can guarantee WebGL2 or the OES extension.

Example fix

// before
new Phaser.Game({ smoothPixelArt: true, type: Phaser.WEBGL })
// after
new Phaser.Game({ pixelArt: true, type: Phaser.WEBGL })

let cfg = { type: Phaser.WEBGL, smoothPixelArt: true }
if (cfg.smoothPixelArt) {
  const c = document.createElement('canvas')
  const gl2 = c.getContext('webgl2')
  const gl1 = !gl2 && c.getContext('webgl')
  const hasDerivatives = !!gl2 || !!(gl1 && gl1.getExtension('OES_standard_derivatives'))
  if (!hasDerivatives) {
    cfg = { ...cfg, smoothPixelArt: false, pixelArt: true }
  }
}
const game = new Phaser.Game(cfg)

const webgl1HasDerivatives = () => {
  const c = document.createElement('canvas')
  if (c.getContext('webgl2')) return true
  const gl = c.getContext('webgl')
  return !!gl && !!gl.getExtension('OES_standard_derivatives')
}

try {
  game = new Phaser.Game({ type: Phaser.WEBGL, smoothPixelArt: true, ... })
} catch (e) {
  if (/OES_standard_derivatives/.test(e.message)) {
    game = new Phaser.Game({ type: Phaser.WEBGL, pixelArt: true, ... })
  } else { throw e }
}

When it happens

Trigger: Configuring `render: { smoothPixelArt: true }` (or top-level `smoothPixelArt: true`) on a WebGL1 context lacking OES_standard_derivatives. Config.js:409 reads this flag; WebGL2 has derivatives built-in so the branch is skipped.

Common situations: Enabling smoothPixelArt for crisp scaled pixel art, then deploying to an old WebGL1 device without the derivatives extension; testing on a minimal software GL backend.

Related errors

• ANGLE_instanced_arrays extension not supported. Required for
• OES_vertex_array_object extension not supported. Required fo
• BatchHandler must have a name
• Must set explicit renderType in custom environment
• Cannot create WebGL context, aborting.

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