{"record":{"id":"c2e56489925e67ce","repo":"mrdoob/three.js","slug":"three-webglrenderer-error-creating-webgl-context","errorCode":null,"errorMessage":"THREE.WebGLRenderer: Error creating WebGL context with your selected attributes.","messagePattern":"THREE\\.WebGLRenderer: Error creating WebGL context with your selected attributes\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/renderers/WebGLRenderer.js","lineNumber":409,"sourceCode":"\t\t\t// OffscreenCanvas does not have setAttribute, see #22811\n\t\t\tif ( 'setAttribute' in canvas ) canvas.setAttribute( 'data-engine', `three.js r${REVISION}` );\n\n\t\t\t// event listeners must be registered before WebGL context is created, see #12753\n\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","sourceCodeStart":391,"sourceCodeEnd":427,"githubUrl":"https://github.com/mrdoob/three.js/blob/da05705fa31f02710c19772a2aa70c7454807f0c/src/renderers/WebGLRenderer.js#L391-L427","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst renderer = new THREE.WebGLRenderer( { canvas, antialias: true, failIfMajorPerformanceCaveat: true, desynchronized: true } );\n\n// after\nconst renderer = new THREE.WebGLRenderer( { canvas, antialias: true, failIfMajorPerformanceCaveat: false } );","handlingStrategy":"fallback","validationCode":"// Probe which attribute set the driver accepts.\nfunction probeAttributes( canvas, attrs ) {\n  const c = canvas.getContext( 'webgl2', attrs );\n  return c !== null;\n}","typeGuard":null,"tryCatchPattern":"try {\n  renderer = new THREE.WebGLRenderer( { canvas, antialias: true, failIfMajorPerformanceCaveat: true } );\n} catch ( e ) {\n  if ( /Error creating WebGL context with your selected attributes/.test( e.message ) ) {\n    // Fallback: drop the offending attributes.\n    renderer = new THREE.WebGLRenderer( { canvas, antialias: true, failIfMajorPerformanceCaveat: false } );\n  } else { throw e; }\n}","preventionTips":["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."],"tags":["webglrenderer","context-creation","context-attributes","environment"],"backgroundTag":null,"analyzedSha":"da05705fa31f02710c19772a2aa70c7454807f0c","analyzedAt":"2026-08-12T22:51:37.160Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}