What causes ""columns" must be >= 1, but got ${JSON.stringify(r.columns)}" in remotion-dev/remotion?

Keep columns >= 1 (documented range is 1..400).

remotion-dev/remotion · error · TypeError

"columns" must be >= 1, but got ${JSON.stringify(r.columns)}

Error message

"columns" must be >= 1, but got ${JSON.stringify(r.columns)}

What it means

pixelDissolve() requires 'columns' to be at least 1 after defaults are applied (default is 10). The check fires after integer/finite validation, throwing a TypeError showing the resolved value when columns < 1, so a zero/negative grid never reaches the shader.

Source

Thrown at packages/effects/src/pixel-dissolve.ts:114

	}
};

const validatePixelDissolveParams = (params: PixelDissolveParams): void => {
	assertEffectParamsObject(params, 'Pixel Dissolve');
	assertOptionalFiniteNumber(params.progress, 'progress');
	assertOptionalFiniteNumber(params.columns, 'columns');
	assertOptionalFiniteNumber(params.rows, 'rows');
	assertOptionalFiniteNumber(params.seed, 'seed');
	assertOptionalFiniteNumber(params.feather, 'feather');
	assertOptionalIntegerNumber(params.columns, 'columns');
	assertOptionalIntegerNumber(params.rows, 'rows');

	const r = resolve(params);
	validateUnitInterval(r.progress, 'progress');
	validateUnitInterval(r.feather, 'feather');

	if (r.columns < 1) {
		throw new TypeError(
			`"columns" must be >= 1, but got ${JSON.stringify(r.columns)}`,
		);
	}

	if (r.rows < 1) {
		throw new TypeError(
			`"rows" must be >= 1, but got ${JSON.stringify(r.rows)}`,
		);
	}
};

type PixelDissolveState = {
	readonly gl: WebGL2RenderingContext;
	readonly program: WebGLProgram;
	readonly vao: WebGLVertexArrayObject;
	readonly vbo: WebGLBuffer;
	readonly texture: WebGLTexture;
	readonly uSource: WebGLUniformLocation | null;

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Keep columns >= 1 (documented range is 1..400).
Clamp animated values: Math.max(1, Math.round(value)).
To remove the effect, animate progress to 0/1 or drop the effect from the stack rather than zeroing columns.

Example fix

// before
pixelDissolve({ columns: animatedCols }) // hits 0

// after
pixelDissolve({ columns: Math.max(1, Math.round(animatedCols)) })

Defensive patterns

Strategy: validation

Validate before calling

// Keep columns within the documented range.
const columns = clamp(Math.round(rawColumns), 1, 400);
pixelDissolve({ columns });
// where clamp(n, lo, hi) = Math.min(hi, Math.max(lo, n))

Type guard

const isValidColumns = (v: unknown): v is number =>
  typeof v === 'number' && Number.isInteger(v) && v >= 1;

Prevention

Clamp animated columns with Math.max(1, Math.round(value)).
Fade the effect via the 'progress' prop instead of zeroing columns.
Reject zero/negative values from external config at the boundary.
Validate against the schema min (1) and max (400) before rendering.

When it happens

Trigger: Calling pixelDissolve({ columns: 0 }) or pixelDissolve({ columns: -3 }), or animating columns down to zero/negative. Checked on the resolved value in validatePixelDissolveParams.

Common situations: Animating columns toward zero to 'disable' the effect; negative values from inverted config; unit conversion producing zero at boundary frames.

Related errors

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