{"record":{"id":"4ac1584db3ef46db","repo":"remotion-dev/remotion","slug":"unknown-program-link-error","errorCode":null,"errorMessage":"Unknown program link error","messagePattern":"Unknown program link error","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/effects/src/white-noise.ts","lineNumber":145,"sourceCode":"\tfragmentSource: string,\n): WebGLProgram => {\n\tconst vertex = compileShader(gl, gl.VERTEX_SHADER, vertexSource);\n\tconst fragment = compileShader(gl, gl.FRAGMENT_SHADER, fragmentSource);\n\tconst program = gl.createProgram();\n\tif (!program) {\n\t\tthrow new Error('Failed to create program');\n\t}\n\n\tgl.attachShader(program, vertex);\n\tgl.attachShader(program, fragment);\n\tgl.linkProgram(program);\n\tgl.deleteShader(vertex);\n\tgl.deleteShader(fragment);\n\n\tif (!gl.getProgramParameter(program, gl.LINK_STATUS)) {\n\t\tconst info = gl.getProgramInfoLog(program) ?? 'Unknown program link error';\n\t\tgl.deleteProgram(program);\n\t\tthrow new Error(info);\n\t}\n\n\treturn program;\n};\n\nconst createWhiteNoiseState = (\n\tgl: WebGL2RenderingContext,\n\tvertexSource: string,\n\tfragmentSource: string,\n): WhiteNoiseState => {\n\tconst program = createProgram(gl, vertexSource, fragmentSource);\n\tconst vao = gl.createVertexArray();\n\tconst vbo = gl.createBuffer();\n\tconst texture = gl.createTexture();\n\n\tif (!vao || !vbo || !texture) {\n\t\tthrow new Error('Failed to create WebGL resources');\n\t}","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/effects/src/white-noise.ts#L127-L163","documentation":"When the white noise program fails gl.LINK_STATUS, the effect reads gl.getProgramInfoLog; if that returns null it throws the literal 'Unknown program link error'. The vertex/fragment shaders and program object are library-internal constants, so a link failure with no diagnostic points to a driver/compiler bug or context loss during linking — not to user input or GLSL the caller controls.","triggerScenarios":"createProgram in white-noise.ts: getProgramParameter(LINK_STATUS) is false AND getProgramInfoLog returns null/empty, triggering the fallback throw.","commonSituations":"Driver linker that fails silently on GLSL-ES 3.00 (#version 300 es) programs; context lost mid-link; software renderer with incomplete program linking; GPU memory exhaustion during link.","solutions":["Render headless with Remotion's bundled Chromium and its known-good SwiftShader; do not pass --disable-gpu.","Update or replace GPU drivers, especially on the failing host.","Ensure the context is not lost before linking (isContextLost()) and re-mount on webglcontextlost.","Lower concurrent WebGL effects to avoid memory pressure during link.","If isolated to one GPU vendor, file a driver bug — the shaders are valid GLSL-ES 3.00."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Cannot prevent a driver linker failure-with-no-log from the caller.\n// Pre-check context health and use a known-good renderer.\nconst gl = document.createElement('canvas').getContext('webgl2');\nconst ok = gl != null && !gl.isContextLost();","typeGuard":"const contextLooksHealthy = (): boolean => {\n  const gl = document.createElement('canvas').getContext('webgl2');\n  return gl != null && !gl.isContextLost();\n};","tryCatchPattern":"try {\n  return <VideoEffects effects={[whiteNoise({amount: 0.4})]} />;\n} catch (err) {\n  if (err instanceof Error && err.message === 'Unknown program link error') {\n    return <Video />; // driver linker fault; skip the effect\n  }\n  throw err;\n}","preventionTips":["Render with Remotion's bundled Chromium and known-good SwiftShader; avoid --disable-gpu.","Update GPU drivers on render hosts.","Confirm context is not lost before rendering; re-mount on webglcontextlost.","Keep concurrent WebGL effects low to avoid memory pressure during link."],"tags":["webgl","shader","gpu","driver","linking"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}