remotion-dev/remotion · error · Error

Failed to create WebGL program

Error message

Failed to create WebGL program

What it means

The speckle() effect's linkProgram() in packages/effects/src/speckle.ts calls gl.createProgram(); if it returns null the effect throws 'Failed to create WebGL program'. The shaders compiled, but the context cannot allocate a program object — typically due to context loss or a driver program-object limit being reached with many live WebGL2 effects.

Source

Thrown at packages/effects/src/speckle.ts:187

	gl.shaderSource(shader, source);
	gl.compileShader(shader);
	if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
		const log = gl.getShaderInfoLog(shader);
		gl.deleteShader(shader);
		throw new Error(`Speckle shader compile failed: ${log ?? '(no log)'}`);
	}

	return shader;
};

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

	return program;
};

export const speckle = createEffect<SpeckleParams, SpeckleState>({
	type: 'dev.remotion.effects.speckle',
	label: 'speckle()',
	documentationLink: 'https://www.remotion.dev/docs/effects/speckle',

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Use ANGLE (--gl=angle / chromiumOptions.gl='angle' / Studio OpenGL=angle).
2. Lower concurrency and the count of simultaneous WebGL2 effects.
3. Ensure effect cleanup (gl.deleteProgram) runs so program handles are freed.
4. Render on a host with a supported GPU and current drivers.

Example fix

// before
await renderMedia({ composition, serveUrl });
// after
await renderMedia({ composition, serveUrl, chromiumOptions: { gl: 'angle' } });

function webgl2Available(): boolean {
  try {
    return !!document.createElement('canvas').getContext('webgl2');
  } catch {
    return false;
  }
}

try {
  await renderMedia({ composition, codec: 'h264', chromiumOptions: { gl: 'angle' } });
} catch (err) {
  if (err instanceof Error && /Failed to create WebGL program/.test(err.message)) {
    console.error('speckle() could not allocate a WebGL program (context lost/exhausted). Lower concurrency or switch GL backend.', err);
    throw err;
  }
  throw err;
}

When it happens

Trigger: Context loss or program-resource exhaustion between shader compile and program creation inside the speckle setup; a driver imposing a low ceiling on live program objects when numerous WebGL2 effects are initialized concurrently.

Common situations: High render concurrency with many stacked WebGL2 effects; long-running renders leaking programs; headless/CI hosts without a real GPU; driver crash/reset during setup.

Related errors

• Failed to create WebGL shader
• Failed to create WebGL buffer
• Failed to create WebGL shader
• Failed to create WebGL program
• Failed to create WebGL vertex array

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