{"record":{"id":"770b2d3f25cf0d8d","repo":"mrdoob/three.js","slug":"three-webglrenderer-error-creating-webgl-context-770b2d","errorCode":null,"errorMessage":"THREE.WebGLRenderer: Error creating WebGL context.","messagePattern":"THREE\\.WebGLRenderer: Error creating WebGL context\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/renderers/WebGLRenderer.js","lineNumber":413,"sourceCode":"\t\t\tcanvas.addEventListener( 'webglcontextlost', onContextLost, false );\n\t\t\tcanvas.addEventListener( 'webglcontextrestored', onContextRestore, false );\n\t\t\tcanvas.addEventListener( 'webglcontextcreationerror', onContextCreationError, false );\n\n\t\t\tif ( _gl === null ) {\n\n\t\t\t\tconst contextName = 'webgl2';\n\n\t\t\t\t_gl = getContext( contextName, contextAttributes );\n\n\t\t\t\tif ( _gl === null ) {\n\n\t\t\t\t\tif ( getContext( contextName ) ) {\n\n\t\t\t\t\t\tthrow new Error( 'THREE.WebGLRenderer: Error creating WebGL context with your selected attributes.' );\n\n\t\t\t\t\t} else {\n\n\t\t\t\t\t\tthrow new Error( 'THREE.WebGLRenderer: Error creating WebGL context.' );\n\n\t\t\t\t\t}\n\n\t\t\t\t}\n\n\t\t\t}\n\n\t\t} catch ( e ) {\n\n\t\t\terror( 'WebGLRenderer: ' + e.message );\n\t\t\tthrow e;\n\n\t\t}\n\n\t\tlet extensions, capabilities, state, info;\n\t\tlet properties, textures, environments, attributes, geometries, objects;\n\t\tlet programCache, materials, renderLists, renderStates, clipping, shadowMap;\n","sourceCodeStart":395,"sourceCodeEnd":431,"githubUrl":"https://github.com/mrdoob/three.js/blob/da05705fa31f02710c19772a2aa70c7454807f0c/src/renderers/WebGLRenderer.js#L395-L431","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Enable WebGL2 in the environment: launch headless Chrome with --enable-unsafe-swiftshader / --use-gl=swiftshader / --ignore-gpu-blocklist.","Detect WebGL2 support up front (canvas.getContext('webgl2') === null) and show a graceful fallback instead of constructing the renderer.","Update GPU drivers / enable hardware acceleration in the browser settings.","On the server, avoid importing/constructing the renderer; gate rendering code behind a browser check."],"exampleFix":"// before\nconst renderer = new THREE.WebGLRenderer(); // throws in headless w/o webgl2\n\n// after\nfunction supportsWebGL2() {\n  try { return !!document.createElement( 'canvas' ).getContext( 'webgl2' ); }\n  catch ( e ) { return false; }\n}\nif ( !supportsWebGL2() ) { showFallbackMessage(); }\nelse { const renderer = new THREE.WebGLRenderer(); }","handlingStrategy":"fallback","validationCode":"function supportsWebGL2() {\n  try { return !!document.createElement( 'canvas' ).getContext( 'webgl2' ); }\n  catch ( e ) { return false; }\n}\nif ( !supportsWebGL2() ) showWebGL2MissingMessage();","typeGuard":null,"tryCatchPattern":"try {\n  renderer = new THREE.WebGLRenderer();\n} catch ( e ) {\n  if ( /Error creating WebGL context\\.$/.test( e.message ) ) {\n    showFallbackUI(); // no WebGL2 available — cannot recover at runtime\n  } else { throw e; }\n}","preventionTips":["Detect WebGL2 before constructing the renderer and show a fallback.","In headless/CI Chrome, pass --enable-unsafe-swiftshader / --use-gl=swiftshader.","Keep renderer construction out of server-side render paths.","Prompt users to enable hardware acceleration / update drivers."],"tags":["webglrenderer","context-creation","no-webgl2","environment","headless"],"backgroundTag":null,"analyzedSha":"da05705fa31f02710c19772a2aa70c7454807f0c","analyzedAt":"2026-08-12T22:51:37.160Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}