mrdoob/three.js · critical · Error

THREE.WebGLRenderer: Error creating WebGL context with your

Error message

THREE.WebGLRenderer: Error creating WebGL context with your selected attributes.

What it means

Thrown during WebGLRenderer.init/_getContext when getContext('webgl2', contextAttributes) returns null but getContext('webgl2') with no attributes succeeds. This isolates the failure to the requested context attributes (e.g. antialias, alpha, stencil, powerPreference, failIfMajorPerformanceCaveat) being rejected by the implementation.

Source

Thrown at src/renderers/WebGLRenderer.js:409

			// OffscreenCanvas does not have setAttribute, see #22811
			if ( 'setAttribute' in canvas ) canvas.setAttribute( 'data-engine', `three.js r${REVISION}` );

			// event listeners must be registered before WebGL context is created, see #12753
			canvas.addEventListener( 'webglcontextlost', onContextLost, false );
			canvas.addEventListener( 'webglcontextrestored', onContextRestore, false );
			canvas.addEventListener( 'webglcontextcreationerror', onContextCreationError, false );

			if ( _gl === null ) {

				const contextName = 'webgl2';

				_gl = getContext( contextName, contextAttributes );

				if ( _gl === null ) {

					if ( getContext( contextName ) ) {

						throw new Error( 'THREE.WebGLRenderer: Error creating WebGL context with your selected attributes.' );

					} else {

						throw new Error( 'THREE.WebGLRenderer: Error creating WebGL context.' );

					}

				}

			}

		} catch ( e ) {

			error( 'WebGLRenderer: ' + e.message );
			throw e;

		}

View on GitHub (pinned to da05705fa3)

Solutions

Relax contextAttributes: remove failIfMajorPerformanceCaveat, antialias, or deserialized/desynchronized flags one at a time to find the culprit.
Set failIfMajorPerformanceCaveat:false (or omit it) when running on software renderers.
Provide a minimal attribute set ({ alpha, antialias }) and add back features incrementally.
Test the target environment with a standalone getContext('webgl2', attrs) probe to surface the driver error via the 'webglcontextcreationerror' event.

Example fix

// before
const renderer = new THREE.WebGLRenderer( { canvas, antialias: true, failIfMajorPerformanceCaveat: true, desynchronized: true } );

// after
const renderer = new THREE.WebGLRenderer( { canvas, antialias: true, failIfMajorPerformanceCaveat: false } );

Defensive patterns

Strategy: fallback

Validate before calling

// Probe which attribute set the driver accepts.
function probeAttributes( canvas, attrs ) {
  const c = canvas.getContext( 'webgl2', attrs );
  return c !== null;
}

Try / catch

try {
  renderer = new THREE.WebGLRenderer( { canvas, antialias: true, failIfMajorPerformanceCaveat: true } );
} catch ( e ) {
  if ( /Error creating WebGL context with your selected attributes/.test( e.message ) ) {
    // Fallback: drop the offending attributes.
    renderer = new THREE.WebGLRenderer( { canvas, antialias: true, failIfMajorPerformanceCaveat: false } );
  } else { throw e; }
}

Prevention

Avoid failIfMajorPerformanceCaveat:true unless you require it.
Start with a minimal attribute set and add features incrementally.
Listen for the 'webglcontextcreationerror' event during dev to see the driver reason.
Test on software renderers (SwiftShader) where attribute rejection is common.

When it happens

Trigger: Passing contextAttributes the GPU/driver/browser refuses: failIfMajorPerformanceCaveat:true on a software-rendered device; incompatible desynchronized/antialias stencil combos; requesting attributes unsupported in a headless or virtual GPU.

Common situations: Setting failIfMajorPerformanceCaveat:true on SwiftShader/software WebGL; requesting antialias with a stencil/depth config the driver dislikes; automated test runners (Puppeteer/Playwright) on virtual displays; specific mobile GPUs rejecting attribute combinations.

Related errors

AI-assisted analysis of mrdoob/three.js@da05705fa3 (2026-08-12). Data as JSON: /api/errors/c2e56489925e67ce. Report an issue: GitHub.