remotion-dev/remotion · error · Error

Halftone linear gradient program link failed: ${log ?? '(no

Error message

Halftone linear gradient program link failed: ${log ?? '(no log)'}

What it means

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.

Source

Thrown at packages/effects/src/halftone-linear-gradient.ts:408

};

const linkProgram = (
	gl: WebGL2RenderingContext,
	vs: WebGLShader,
	fs: WebGLShader,
): WebGLProgram => {
	const program = gl.createProgram();
	if (!program) {
		throw new Error('Failed to create WebGL program');
	}

	gl.attachShader(program, vs);
	gl.attachShader(program, fs);
	gl.linkProgram(program);
	if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
		const log = gl.getProgramInfoLog(program);
		gl.deleteProgram(program);
		throw new Error(
			`Halftone linear gradient program link failed: ${log ?? '(no log)'}`,
		);
	}

	return program;
};

export const halftoneLinearGradient = createEffect<
	HalftoneLinearGradientParams,
	HalftoneLinearGradientState
>({
	type: 'dev.remotion.effects.halftoneLinearGradient',
	label: 'halftoneLinearGradient()',
	documentationLink:
		'https://www.remotion.dev/docs/effects/halftone-linear-gradient',
	backend: 'webgl2',
	calculateKey: (params) => {
		const r = resolve(params);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. 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.
2. 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.
3. 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.
4. If the failure is transient (context loss), restart the render once; the GL context is recreated on a fresh process.

Example fix

// before: headless render with an incompatible GL backend
await renderMedia({ serveUrl, codec: 'h264', chromiumOptions: { gl: 'swiftshader' } });

// after: let Remotion pick its default headless GPU stack
await renderMedia({ serveUrl, codec: 'h264' });

// halftone-linear-gradient needs a working WebGL2 linker; wrap the effect render in a try and fall back.
try {
  // ...apply halftoneLinearGradient()
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Halftone linear gradient program link failed')) {
    // log the driver info log embedded in the message, then degrade gracefully
    console.error('WebGL2 link failed for halftone-linear-gradient:', e.message);
    // fall back to a 2D-backend effect or skip
  } else {
    throw e;
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to create WebGL vertex array
• Failed to create WebGL buffer
• Failed to acquire 2D context for color parsing
• Halftone shader compile failed: ${log ?? '(no log)'}
• Halftone program link failed: ${log ?? '(no log)'}

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/e511c88f99d3701f. Report an issue: GitHub.