What causes ""samples" must be an integer, but got ${samples}" in remotion-dev/remotion?

Pass an integer `samples` between 1 and 64 (default 32).

remotion-dev/remotion · error · TypeError

"samples" must be an integer, but got ${samples}

Error message

"samples" must be an integer, but got ${samples}

What it means

Thrown by the `lightTrail()` effect's `validateSamples()` when the resolved `samples` value is not an integer. `samples` controls the number of trail accumulation passes in the GLSL loop (declared as `int` with a compile-time `MAX_SAMPLES = 64`), so fractional values are meaningless and rejected with a TypeError before reaching the GPU.

Source

Thrown at packages/effects/src/light-trail/index.ts:129

	readonly decay: number;
	readonly threshold: number;
	readonly samples: number;
	readonly color: string;
};

const resolve = (p: LightTrailParams): LightTrailResolved => ({
	direction: p.direction ?? DEFAULT_DIRECTION,
	distance: p.distance ?? DEFAULT_DISTANCE,
	intensity: p.intensity ?? DEFAULT_INTENSITY,
	decay: p.decay ?? DEFAULT_DECAY,
	threshold: p.threshold ?? DEFAULT_THRESHOLD,
	samples: p.samples ?? DEFAULT_SAMPLES,
	color: p.color ?? DEFAULT_COLOR,
});

const validateSamples = (samples: number): void => {
	if (!Number.isInteger(samples)) {
		throw new TypeError(`"samples" must be an integer, but got ${samples}`);
	}

	if (samples < 1) {
		throw new TypeError(`"samples" must be >= 1, but got ${samples}`);
	}

	if (samples > MAX_SAMPLES) {
		throw new TypeError(
			`"samples" must be <= ${MAX_SAMPLES}, but got ${samples}`,
		);
	}
};

const validateLightTrailParams = (params: LightTrailParams): void => {
	assertEffectParamsObject(params, 'Light trail');
	assertOptionalFiniteNumber(params.direction, 'direction');
	assertOptionalFiniteNumber(params.distance, 'distance');
	assertOptionalFiniteNumber(params.intensity, 'intensity');

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass an integer `samples` between 1 and 64 (default 32).
Wrap computed values with `Math.round()` before passing them in.
If animating, round the interpolated output or animate in integer steps.

Example fix

// before
lightTrail({samples: total / 3})

// after
lightTrail({samples: Math.round(total / 3)})

Defensive patterns

Strategy: validation

Validate before calling

if (typeof params.samples === 'number' && !Number.isInteger(params.samples)) {
  params = {...params, samples: Math.round(params.samples)};
}

Type guard

const isSamplesSafe = (s: number | undefined): boolean =>
  s === undefined || (Number.isInteger(s) && s >= 1 && s <= 64);

Prevention

Always Math.round() computed sample counts before passing them in.
Set slider steps to 1 so fractional samples can't be selected.
When animating samples, round the interpolated value or use integer keyframes.

When it happens

Trigger: Passing `lightTrail({samples: 32.5})`, a fractional result of division (e.g. `maxSamples / 2` when maxSamples is odd), or animating `samples` with an interpolate whose easing produces fractional output.

Common situations: Slider with a non-integer step; computed sample counts from arithmetic; rounding mistakes where the user assumed the library would floor the value.

Related errors

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