{"record":{"id":"e511c88f99d3701f","repo":"remotion-dev/remotion","slug":"halftone-linear-gradient-program-link-failed-lo","errorCode":null,"errorMessage":"Halftone linear gradient program link failed: ${log ?? '(no log)'}","messagePattern":"Halftone linear gradient program link failed: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/effects/src/halftone-linear-gradient.ts","lineNumber":408,"sourceCode":"};\n\nconst linkProgram = (\n\tgl: WebGL2RenderingContext,\n\tvs: WebGLShader,\n\tfs: WebGLShader,\n): WebGLProgram => {\n\tconst program = gl.createProgram();\n\tif (!program) {\n\t\tthrow new Error('Failed to create WebGL program');\n\t}\n\n\tgl.attachShader(program, vs);\n\tgl.attachShader(program, fs);\n\tgl.linkProgram(program);\n\tif (!gl.getProgramParameter(program, gl.LINK_STATUS)) {\n\t\tconst log = gl.getProgramInfoLog(program);\n\t\tgl.deleteProgram(program);\n\t\tthrow new Error(\n\t\t\t`Halftone linear gradient program link failed: ${log ?? '(no log)'}`,\n\t\t);\n\t}\n\n\treturn program;\n};\n\nexport const halftoneLinearGradient = createEffect<\n\tHalftoneLinearGradientParams,\n\tHalftoneLinearGradientState\n>({\n\ttype: 'dev.remotion.effects.halftoneLinearGradient',\n\tlabel: 'halftoneLinearGradient()',\n\tdocumentationLink:\n\t\t'https://www.remotion.dev/docs/effects/halftone-linear-gradient',\n\tbackend: 'webgl2',\n\tcalculateKey: (params) => {\n\t\tconst r = resolve(params);","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/effects/src/halftone-linear-gradient.ts#L390-L426","documentation":"Thrown by the linkProgram() helper of the halftone-linear-gradient WebGL2 effect when gl.linkProgram finishes but gl.getProgramParameter(program, gl.LINK_STATUS) is falsy. The vertex and fragment shaders compiled individually, but the GPU/driver refused to link them into a single program; the driver's info log is appended (or '(no log)' if the driver returned nothing). Because both shaders are fixed strings shipped inside @remotion/effects, a normal user cannot cause this with bad parameters — it indicates a GPU driver bug, a WebGL2 implementation gap, or a corrupt GLSL toolchain in the rendering environment.","triggerScenarios":"Calling halftoneLinearGradient() in a composition that is then rendered or previewed on a machine whose WebGL2 driver links the effect's vertex/fragment pair unsuccessfully. Concretely: render machines using software SwiftShader with old GLSL ES 3.00 gaps, virtualised/headless Chrome without GPU acceleration, or a GPU driver crash mid-session that left the context in a degraded state.","commonSituations":"CI or server-side rendering with --gl=swiftshader or a headless Chrome that advertises WebGL2 but links poorly; rendering on a remote Linux box with nouveau/mesa drivers; a machine that resumed from sleep with a lost GL context; rare transient driver faults.","solutions":["Read the info log embedded in the error message — it names the exact link error (e.g. varying mismatch, unsupported extension) which points at the driver capability gap.","Render on a machine with a working WebGL2 stack: enable hardware acceleration, or use a Remotion Chrome for Testing build that ships known-good GPU support.","If rendering headless, pass a Chromium GPU flag known to work (e.g. --use-gl=angle --use-angle=gl) or rely on Remotion's default headless shell instead of a custom swiftshader invocation.","If the failure is transient (context loss), restart the render once; the GL context is recreated on a fresh process."],"exampleFix":"// before: headless render with an incompatible GL backend\nawait renderMedia({ serveUrl, codec: 'h264', chromiumOptions: { gl: 'swiftshader' } });\n\n// after: let Remotion pick its default headless GPU stack\nawait renderMedia({ serveUrl, codec: 'h264' });","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// halftone-linear-gradient needs a working WebGL2 linker; wrap the effect render in a try and fall back.\ntry {\n  // ...apply halftoneLinearGradient()\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Halftone linear gradient program link failed')) {\n    // log the driver info log embedded in the message, then degrade gracefully\n    console.error('WebGL2 link failed for halftone-linear-gradient:', e.message);\n    // fall back to a 2D-backend effect or skip\n  } else {\n    throw e;\n  }\n}","preventionTips":["Render with hardware acceleration enabled or use Remotion's bundled headless shell rather than a custom swiftshader invocation.","Keep GPU drivers current so GLSL ES 3.00 linking works.","In CI, smoke-test one WebGL2-backed effect before running the full render to fail fast on driver issues."],"tags":["webgl","halftone-linear-gradient","gpu-driver","rendering","headless"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}