remotion-dev/remotion · error · Error

"blockSize" must be >= 1

Error message

"blockSize" must be >= 1

What it means

Thrown by validatePixelateParams when the user-supplied (or defaulted) blockSize is less than 1. The schema declares blockSize with min:1, and this runtime guard enforces it before any GL work happens. A blockSize below 1 is meaningless for the pixelation math (it would divide UV space by a non-positive number) and is rejected early.

Source

Thrown at packages/effects/src/pixelate.ts:37

} as const satisfies InteractivitySchema;

export type PixelateParams = {
	readonly blockSize?: number;
};

type PixelateResolved = {
	blockSize: number;
};

const resolve = (p: PixelateParams): PixelateResolved => ({
	blockSize: p.blockSize ?? DEFAULT_BLOCK_SIZE,
});

const validatePixelateParams = (params: PixelateParams): void => {
	assertEffectParamsObject(params, 'Pixelate');
	assertOptionalFiniteNumber(params.blockSize, 'blockSize');
	if ((params.blockSize ?? DEFAULT_BLOCK_SIZE) < 1) {
		throw new Error('"blockSize" must be >= 1');
	}
};

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

const VERTEX_SHADER = /* glsl */ `#version 300 es

in vec2 aPos;
in vec2 aUv;

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Set blockSize to at least 1, e.g. `pixelate({blockSize: 1})` for the finest allowed pixelation.
2. When animating blockSize, clamp the interpolated value with `Math.max(1, value)` before passing it.
3. If you want 'no pixelation', omit blockSize entirely (defaults to 20) or remove the pixelate effect from the sequence rather than driving blockSize toward 0.
4. Audit interpolate() ranges and spring physics outputs that feed blockSize to ensure they never dip below 1.

Example fix

// before
import {pixelate} from '@remotion/effects';
const e = pixelate({blockSize: 0}); // throws '"blockSize" must be >= 1'

// after
import {interpolate, useCurrentFrame} from 'remotion';
const frame = useCurrentFrame();
const raw = interpolate(frame, [0, 60], [0, 40]);
const e = pixelate({blockSize: Math.max(1, Math.round(raw))});

function validateBlockSize(v: unknown): number {
  if (v === undefined) return 20; // DEFAULT_BLOCK_SIZE
  if (typeof v !== 'number' || !Number.isFinite(v)) {
    throw new TypeError('blockSize must be a finite number');
  }
  if (v < 1) throw new Error('"blockSize" must be >= 1');
  return v;
}
const blockSize = validateBlockSize(maybeBlockSize);

function isValidBlockSize(v: unknown): v is number {
  return typeof v === 'number' && Number.isFinite(v) && v >= 1;
}

When it happens

Trigger: Calling `pixelate({blockSize: 0})`, `pixelate({blockSize: -5})`, or passing a fractional value below 1 such as `pixelate({blockSize: 0.5})`. The check uses `(params.blockSize ?? DEFAULT_BLOCK_SIZE) < 1`, so an explicit 0 or negative trips it; undefined falls through to the default of 20 and is safe.

Common situations: Animation that tweens blockSize toward zero and overshoots; an interpolated value from a schema-driven UI control that allowed values below the documented min; user copies a value from a different effect with a different scale; passing a string or NaN will trip an earlier assertOptionalFiniteNumber check, not this one.

Related errors

• A "duration" of a spring must be a "number" but is "${typeof
• "${name}" must be greater than 0, but got ${JSON.stringify(v
• "${name}" must be greater than or equal to 0, but got ${JSON
• "colors" must be an array with at least 2 colors, but got ${
• "exposure" must be >= ${MIN_EXPOSURE}, but got ${JSON.string

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