mrdoob/three.js · critical · Error

THREE.WebGLRenderer: Error creating WebGL context.

Error message

THREE.WebGLRenderer: Error creating WebGL context.

What it means

Thrown during WebGLRenderer context acquisition when getContext('webgl2') returns null even with no attributes — the environment has no usable WebGL2 at all. This is distinct from the attributes error: here WebGL2 itself is unavailable, not merely the requested options.

Source

Thrown at src/renderers/WebGLRenderer.js:413

			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;

		}

		let extensions, capabilities, state, info;
		let properties, textures, environments, attributes, geometries, objects;
		let programCache, materials, renderLists, renderStates, clipping, shadowMap;

View on GitHub (pinned to da05705fa3)

Solutions

1. Enable WebGL2 in the environment: launch headless Chrome with --enable-unsafe-swiftshader / --use-gl=swiftshader / --ignore-gpu-blocklist.
2. Detect WebGL2 support up front (canvas.getContext('webgl2') === null) and show a graceful fallback instead of constructing the renderer.
3. Update GPU drivers / enable hardware acceleration in the browser settings.
4. On the server, avoid importing/constructing the renderer; gate rendering code behind a browser check.

Example fix

// before
const renderer = new THREE.WebGLRenderer(); // throws in headless w/o webgl2

// after
function supportsWebGL2() {
  try { return !!document.createElement( 'canvas' ).getContext( 'webgl2' ); }
  catch ( e ) { return false; }
}
if ( !supportsWebGL2() ) { showFallbackMessage(); }
else { const renderer = new THREE.WebGLRenderer(); }

function supportsWebGL2() {
  try { return !!document.createElement( 'canvas' ).getContext( 'webgl2' ); }
  catch ( e ) { return false; }
}
if ( !supportsWebGL2() ) showWebGL2MissingMessage();

try {
  renderer = new THREE.WebGLRenderer();
} catch ( e ) {
  if ( /Error creating WebGL context\.$/.test( e.message ) ) {
    showFallbackUI(); // no WebGL2 available — cannot recover at runtime
  } else { throw e; }
}

When it happens

Trigger: Running in a browser/headless browser with WebGL2 disabled; a machine whose drivers/blocklist prevent WebGL2; a context lost and never restored; Node.js without a WebGL polyfill; a browser older than the minimum that supports WebGL2.

Common situations: CI/headless Chrome without --use-gl=swiftshader or GPU flags; corporate machines with blocklisted GPU drivers; users with hardware acceleration disabled; Safari/older browsers predating WebGL2; server-side rendering hitting renderer code.

Related errors

• THREE.WebGLRenderer: Error creating WebGL context with your
• THREE.WebGLRenderer: WebGL 1 is not supported since r163.
• THREE.WebGLRenderer: Attached DepthTexture is initialized to
• THREE.WebGLRenderer.readRenderTargetPixels: renderTarget is
• THREE.WebGLRenderer.readRenderTargetPixelsAsync: renderTarge

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