remotion-dev/remotion · critical · Error

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

Error message

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

What it means

Thrown by the wave effect's linkProgram() when gl.linkProgram() succeeds in calling but gl.getProgramParameter(program, gl.LINK_STATUS) returns false. This means the vertex and fragment shaders compiled individually but could not be linked into a single executable program — typically due to mismatched varying declarations, missing attribute bindings, or a GPU driver bug. The error message includes the info log from the GL driver for diagnostics.

Source

Thrown at packages/effects/src/wave/wave-runtime.ts:59

};

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

	return program;
};

const createProgram = (
	gl: WebGL2RenderingContext,
	vertexSource: string,
	fragmentSource: string,
): WebGLProgram => {
	const vs = compileShader(gl, gl.VERTEX_SHADER, vertexSource);
	const fs = compileShader(gl, gl.FRAGMENT_SHADER, fragmentSource);
	const program = linkProgram(gl, vs, fs);
	gl.deleteShader(vs);
	gl.deleteShader(fs);
	return program;
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Update your GPU drivers to the latest version — link failures with valid shaders are almost always driver bugs.
2. If rendering server-side (Remotion Lambda / headless Chrome), ensure the Chrome binary bundled with @remotion/renderer matches the platform's GPU/SwiftShader capabilities and is up to date.
3. Check the browser console for a preceding 'webglcontextlost' event; if the context was lost, the canvas must be recreated before retrying setupWave.
4. Try disabling hardware acceleration in the render environment (or conversely enabling it if currently on software) to switch between the GPU driver and SwiftShader.
5. Report the issue to Remotion with the full info log from the error message and your GPU/driver details (chrome://gpu).

Example fix

// Cannot be fixed from user code — the shaders are internal constants.
// Workaround: fall back to a non-WebGL effect or retry on a fresh canvas.
// before
import {wave} from '@remotion/effects';
const state = setupWave(canvas); // may throw link failure

// after: wrap setup so a context loss or driver bug doesn't crash the render
try {
  const state = setupWave(canvas);
} catch (e) {
  console.error('Wave effect unavailable on this GPU:', (e as Error).message);
  // fall back to a CSS/native effect or skip the wave overlay
}

// Wrap effect application so a link failure (driver bug) degrades gracefully.
// The error originates inside setupWave, so catch at the point of use.
import {wave} from '@remotion/effects';

try {
  // If using the effect via the framework, wrap the component/frame logic
  state = setupWave(canvas);
} catch (e) {
  if ((e as Error).message.startsWith('Program link failed')) {
    // GPU/driver issue — log and skip the effect
    console.warn('Wave effect unavailable:', (e as Error).message);
  } else {
    throw e; // re-throw unrelated errors
  }
}

When it happens

Trigger: Called transitively from setupWave() at packages/effects/src/wave/wave-runtime.ts:118 via createProgram(gl, WAVE_VS, WAVE_FS). The shaders WAVE_VS/WAVE_FS are static library constants, so this fires when the GL driver rejects the linked program — not from user params. Most common when the WebGL2 context is in a degraded state or the GPU driver has a bug with the specific GLSL ES 3.00 construct used.

Common situations: Headless Chromium with SwiftShader software rendering rejecting a GLSL construct; outdated GPU drivers on Windows; a transient WebGL context loss mid-setup; running in a CI environment with a software rasterizer that has partial WebGL2 support; virtual machines with passthrough GPU drivers.

Related errors

• Contour lines shader compile failed: ${log ?? '(no log)'}
• Contour lines program link failed: ${log ?? '(no log)'}
• Shader compile failed: ${log ?? '(no log)'}
• Program link failed: ${log ?? '(no log)'}
• Linear gradient shader compile failed: ${log ?? '(no log)'}

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