{"record":{"id":"5ad3d7b3bc6135fc","repo":"remotion-dev/remotion","slug":"failed-to-create-webgl-shader-5ad3d7","errorCode":null,"errorMessage":"Failed to create WebGL shader","messagePattern":"Failed to create WebGL shader","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/effects/src/mirror/mirror-runtime.ts","lineNumber":29,"sourceCode":"\tvao: WebGLVertexArrayObject;\n\tvbo: WebGLBuffer;\n\ttextureSource: WebGLTexture;\n\tuniforms: {\n\t\tuSource: WebGLUniformLocation | null;\n\t\tuPosition: WebGLUniformLocation | null;\n\t\tuDirection: WebGLUniformLocation | null;\n\t\tuInvert: WebGLUniformLocation | null;\n\t};\n};\n\nconst compileShader = (\n\tgl: WebGL2RenderingContext,\n\ttype: number,\n\tsource: string,\n): WebGLShader => {\n\tconst shader = gl.createShader(type);\n\tif (!shader) {\n\t\tthrow new Error('Failed to create WebGL shader');\n\t}\n\n\tgl.shaderSource(shader, source);\n\tgl.compileShader(shader);\n\tif (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {\n\t\tconst log = gl.getShaderInfoLog(shader);\n\t\tgl.deleteShader(shader);\n\t\tthrow new Error(`Shader compile failed: ${log ?? '(no log)'}`);\n\t}\n\n\treturn shader;\n};\n\nconst linkProgram = (\n\tgl: WebGL2RenderingContext,\n\tvs: WebGLShader,\n\tfs: WebGLShader,\n): WebGLProgram => {","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/effects/src/mirror/mirror-runtime.ts#L11-L47","documentation":"While setting up the mirror effect's WebGL2 pipeline, compileShader called gl.createShader() which returned null instead of a WebGLShader handle. The WebGL2 context exists (an earlier check would have thrown createWebGL2ContextError) but is in an unhealthy state — most commonly due to context loss, GPU resource exhaustion, or a headless environment with inadequate GPU drivers.","triggerScenarios":"The mirror effect's setupMirror runs during rendering; gl.createShader(type) returns null. This happens after the WebGL2 context is acquired but before any shader source is uploaded, indicating the context cannot allocate shader objects.","commonSituations":"CI/headless rendering with software rasterizers or missing GPU flags; too many simultaneous WebGL contexts exhausting driver limits; browser tab crash triggering context loss; VMs or Docker containers without GPU passthrough; corrupted or blacklisted GPU drivers.","solutions":["Ensure the render environment supports WebGL2 — for headless Chrome pass flags like --enable-webgl and --use-gl=angle or --use-gl=swiftshader.","Reduce the number of concurrent WebGL-based effects in a single render.","Update GPU drivers or switch to a software renderer (SwiftShader) in environments without a physical GPU.","If context loss is the cause, retry the render after the browser re-acquires the context."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Check WebGL2 shader allocation capability before using the effect\nconst testCanvas = document.createElement('canvas');\nconst testGl = testCanvas.getContext('webgl2');\nif (testGl) {\n  const testShader = testGl.createShader(testGl.VERTEX_SHADER);\n  if (!testShader) {\n    console.warn('WebGL2 shader allocation failed — mirror effect may not work');\n  }\n  testGl.deleteShader(testShader);\n}","typeGuard":null,"tryCatchPattern":"// Wrap effect usage in try-catch with a non-WebGL fallback\ntry {\n  // apply mirror effect\n} catch (e) {\n  if (e instanceof Error && e.message.includes('WebGL shader')) {\n    console.warn('WebGL unavailable, skipping mirror effect');\n    // fall back to rendering without the effect\n  } else {\n    throw e;\n  }\n}","preventionTips":["Ensure the render environment (especially CI/headless) has working WebGL2 with appropriate Chrome GPU flags.","Monitor WebGL context loss events and handle them gracefully.","Limit the number of concurrent WebGL effects to avoid resource exhaustion."],"tags":["webgl","gpu","environment","mirror-effect","rendering"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}