remotion-dev/remotion · error · Error

Gridlines program link failed: ${log ?? '(no log)'}

Error message

Gridlines program link failed: ${log ?? '(no log)'}

What it means

Thrown by gridlines' linkProgram after gl.linkProgram when LINK_STATUS is false. The driver's program info log is appended. Because both shaders already compiled, a link failure means a shader-interface mismatch or driver bug, not a user parameter problem.

Source

Thrown at packages/effects/src/gridlines.ts:395

};

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(`Gridlines program link failed: ${log ?? '(no log)'}`);
	}

	return program;
};

const rgbaToUniform = (
	rgba: ParsedColorRgba,
): readonly [number, number, number, number] => {
	const [r, g, b, a] = rgba;
	const alpha = a / 255;
	return [(r / 255) * alpha, (g / 255) * alpha, (b / 255) * alpha, alpha];
};

export const gridlines = createEffect<GridlinesParams, GridlinesState>({
	type: 'remotion/gridlines',
	label: 'gridlines()',
	documentationLink: 'https://www.remotion.dev/docs/effects/gridlines',
	backend: 'webgl2',

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Read the appended info log for the mismatch reason.
2. Reproduce on a mainstream desktop GPU with current drivers to confirm the link should succeed.
3. For headless, switch ANGLE backend or update SwiftShader.
4. Update GPU drivers / browser; if a blocklist entry applies, address the underlying GPU/driver issue.

Example fix

// before: stale headless backend produces 'Gridlines program link failed: ...'
NVIDIA driver from 2019 in headless Chrome

// after: update driver + use a conformant backend
latest stable GPU driver; chrome --use-gl=angle --use-angle=swiftshader

// Validate a conformant WebGL2 compiler is present (run the effect in a known-good env first)
const gl = canvas.getContext('webgl2');
if (!gl || gl.isContextLost()) throw new Error('No healthy WebGL2 context');

null

try {
  gridlines.setup(canvas);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Gridlines program link failed')) {
    // driver bug: read info log, switch backend / update drivers
  }
  throw e;
}

When it happens

Trigger: Setup-time linking of the hardcoded Gridlines vertex+fragment shaders. Real causes: varying in/out declarations that do not match across stages, an attribute referenced in GLSL that the driver cannot bind, or a driver bug rejecting a valid program. On WebGL2 hardware this is rare with the shipped shaders, so it usually points to a non-conformant driver.

Common situations: Buggy/outdated GPU drivers; a software renderer (SwiftShader) version with known linking bugs; a GPU on the browser's blocklist being used anyway; rare ANGLE regressions.

Related errors

• Failed to create WebGL program
• Checkerboard program link failed: ${log ?? '(no log)'}
• Failed to create WebGL program
• Program link failed: ${log ?? '(no log)'}
• Gridlines shader compile failed: ${log ?? '(no log)'}

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