{"record":{"id":"65014e932778b0c8","repo":"remotion-dev/remotion","slug":"failed-to-create-webgl-shader-65014e","errorCode":null,"errorMessage":"Failed to create WebGL shader","messagePattern":"Failed to create WebGL shader","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/effects/src/linear-gradient.ts","lineNumber":170,"sourceCode":"\n\treturn clamp(dot(uv - uStart, gradient) / gradientLengthSq, 0.0, 1.0);\n}\n\nvoid main() {\n\tvec2 publicUv = vec2(vUv.x, 1.0 - vUv.y);\n\tvec4 color = mix(uStartColor, uEndColor, gradientProgress(publicUv));\n\tfragColor = vec4(color.rgb * color.a, color.a);\n}\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(\n\t\t\t`Linear gradient shader compile failed: ${log ?? '(no log)'}`,\n\t\t);\n\t}\n\n\treturn shader;\n};\n\nconst createProgram = (gl: WebGL2RenderingContext): WebGLProgram => {\n\tconst vs = compileShader(gl, gl.VERTEX_SHADER, VERTEX_SHADER);\n\tconst fs = compileShader(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/effects/src/linear-gradient.ts#L152-L188","documentation":"Thrown by compileShader() in the linear-gradient effect when gl.createShader() returns null. The WebGL2 context exists but refused to allocate a new shader object, which the library treats as fatal because the effect cannot run without one. It is an environment/resource failure, not a shader-source problem.","triggerScenarios":"Calling linearGradient() in a composition that gets rendered or previewed when the underlying WebGL2 context is lost, GPU memory is exhausted, or the process has exceeded the browser's active-context limit (~16). Also occurs in headless Chrome launched without a working GL backend (no SwiftShader/ANGLE).","commonSituations":"Remotion Lambda/serverless renders where the Chrome GPU process crashed or was culled; local renders with --gl set to a backend the host does not support; many concurrent Studio previews or Player instances each grabbing a context; outdated GPU drivers on the render machine.","solutions":["Retry the render once — a lost context is frequently transient and recovers on a fresh Chrome process.","Pass an explicit GL backend to the renderer, e.g. set the CLI/config GL to angle with swiftshader: `--gl=angle --angle-backend=swiftshader` (or `chrome` / `swangle`), to guarantee software rendering.","Lower concurrency so fewer WebGL contexts live at once: reduce Remotion's `--concurrency` (Lambda `framesPerLambda` / parallelism) or close other Studio tabs.","Update Chrome/Chromium and GPU drivers on the host; if on Lambda, use a Remotion-published layer that ships a known-good Chrome+SwiftShader.","Check the Chrome log for 'GpuProcess crashed' or 'ContextResult::kTransientFailure' to confirm a GPU-process problem rather than an app bug."],"exampleFix":"// before (default GL, fails on a GPU-less host)\n//   npx remotion render MyComp out.mp4\n\n// after — force software GL so createShader always succeeds\n//   npx remotion render MyComp out.mp4 \\\n//       --gl=angle --angle-backend=swiftshader","handlingStrategy":"retry","validationCode":"// Feature-detect WebGL2 before mounting a GPU effect — createShader returning null\n// implies the context is failing even if getContext succeeded.\nfunction supportsWebGL2ShaderAlloc(canvas: HTMLCanvasElement): boolean {\n  const gl = canvas.getContext('webgl2');\n  if (!gl) return false;\n  const probe = gl.createShader(gl.VERTEX_SHADER);\n  const ok = probe !== null;\n  if (probe) gl.deleteShader(probe);\n  gl.getExtension?.('loseContext')?.loseContext?.();\n  return ok;\n}","typeGuard":null,"tryCatchPattern":"// WebGL resource failures are best treated as transient — retry once on a fresh worker.\ntry {\n  renderWithLinearGradient();\n} catch (err) {\n  if (err instanceof Error && err.message === 'Failed to create WebGL shader') {\n    // restart the Chrome/worker context, then retry exactly once\n    await restartRendererWorker();\n    renderWithLinearGradient();\n  } else {\n    throw err;\n  }\n}","preventionTips":["Pin the renderer to a software GL backend (`--gl=angle --angle-backend=swiftshader`) on CPU-only/serverless hosts.","Cap `--concurrency` / framesPerLambda so the browser stays under its ~16 active WebGL context limit.","Use the Remotion-bundled Chrome rather than a system Chrome whose GPU flags may be disabled.","Watch Chrome logs for 'GpuProcess crashed' / 'ContextResult::kTransientFailure' and recycle the worker when seen."],"tags":["webgl","gpu","rendering","remotion","browser-env","resource-exhaustion"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}