{"record":{"id":"61c49d952df47870","repo":"siyuan-note/siyuan","slug":"webgl2-is-unavailable","errorCode":null,"errorMessage":"WebGL2 is unavailable","messagePattern":"WebGL2 is unavailable","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"app/src/layout/dock/graph/webglRenderer.ts","lineNumber":211,"sourceCode":"    private highlightLine = new Float32Array([0, 0, 0, 1]);\n    private highlightPoint = new Float32Array([0, 0, 0, 1]);\n    private nodeColors = new Float32Array();\n    private nodeStates = new Float32Array();\n    private positionVersion = -1;\n    private selectionVersion = -1;\n    private styleVersion = -1;\n\n    constructor(canvas: HTMLCanvasElement) {\n        const gl = canvas.getContext(\"webgl2\", {\n            alpha: true,\n            antialias: true,\n            depth: false,\n            premultipliedAlpha: true,\n            preserveDrawingBuffer: false,\n            stencil: false,\n        });\n        if (!gl) {\n            throw new Error(\"WebGL2 is unavailable\");\n        }\n        this.canvas = canvas;\n        this.gl = gl;\n        this.nodeProgram = this.createProgram(NODE_VERTEX_SHADER, NODE_FRAGMENT_SHADER);\n        this.edgeProgram = this.createProgram(EDGE_VERTEX_SHADER, EDGE_FRAGMENT_SHADER);\n        this.arrowProgram = this.createProgram(ARROW_VERTEX_SHADER, ARROW_FRAGMENT_SHADER);\n        this.nodeVao = this.requireValue(gl.createVertexArray());\n        this.edgeVao = this.requireValue(gl.createVertexArray());\n        this.arrowVao = this.requireValue(gl.createVertexArray());\n        this.nodePositionBuffer = this.createBuffer();\n        this.nodeSizeBuffer = this.createBuffer();\n        this.nodeColorBuffer = this.createBuffer();\n        this.nodeStateBuffer = this.createBuffer();\n        this.edgeEndpointBuffer = this.createBuffer();\n        this.edgeColorBuffer = this.createBuffer();\n        this.edgeStateBuffer = this.createBuffer();\n        this.arrowEndpointBuffer = this.createBuffer();\n        this.arrowSizeBuffer = this.createBuffer();","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/app/src/layout/dock/graph/webglRenderer.ts#L193-L229","documentation":"WebGLRenderer constructor requests canvas.getContext('webgl2', {...}) and throws when it returns null. WebGL2 (GLSL ES 3.00) is required because the shaders use #version 300 es; without it the graph renderer cannot run.","triggerScenarios":"Opening the graph dock in a browser or webview that only supports WebGL1 (older Safari, some embedded WebViews), with hardware acceleration disabled, in a headless environment without GPU access, or after a previous webgl2 context was lost and not restored.","commonSituations":"User disabled GPU acceleration in Electron/Chrome; Linux without proper GPU drivers; VM / remote desktop without GPU passthrough; older mobile webviews that predate WebGL2; Tilt/Mac KVM environments.","solutions":["Enable hardware acceleration in the browser/Electron settings and update GPU drivers.","Feature-detect webgl2 before constructing WebGLRenderer and show a 'Graph requires WebGL2' message instead of crashing.","Listen for the 'webglcontextlost' event on the canvas and tear down the renderer; offer to reload.","For headless/CI use, launch with --use-gl=swiftshader or a software WebGL2 implementation."],"exampleFix":"// before\nconst gl = canvas.getContext('webgl2', opts);\nif (!gl) throw new Error('WebGL2 is unavailable');\n// after\nconst gl = canvas.getContext('webgl2', opts);\nif (!gl) { showMessage('Graph view requires WebGL2. Enable hardware acceleration.'); return null; }","handlingStrategy":"type-guard","validationCode":"function supportsWebGL2(): boolean {\n    try { return !!document.createElement('canvas').getContext('webgl2'); }\n    catch { return false; }\n}","typeGuard":"function webgl2Supported(): boolean {\n    try { return !!document.createElement('canvas').getContext('webgl2'); }\n    catch { return false; }\n}","tryCatchPattern":"try { return new WebGLRenderer(canvas); }\ncatch (e) { showMessage('Graph view requires WebGL2. Enable hardware acceleration.'); return null; }","preventionTips":["Detect webgl2 before constructing the renderer and degrade gracefully.","Listen for 'webglcontextlost' and tear down the renderer cleanly.","Recommend users enable hardware acceleration and update GPU drivers.","In headless/CI use a software WebGL (SwiftShader)."],"tags":["browser","webgl","graph","typescript","feature-detection"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}