remotion-dev/remotion · error · TypeError

"samples" must be <= ${MAX_SAMPLES}, but got ${samples}

Error message

"samples" must be <= ${MAX_SAMPLES}, but got ${samples}

What it means

Thrown by @remotion/effects' lightTrail effect when `samples` exceeds MAX_SAMPLES (64). The upper bound caps GPU cost: each extra sample adds a directional texture fetch in the fragment shader, so 64 is the safety ceiling before frame budgets blow out during rendering.

Source

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

	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');
	assertOptionalFiniteNumber(params.decay, 'decay');
	assertOptionalFiniteNumber(params.threshold, 'threshold');
	assertOptionalFiniteNumber(params.samples, 'samples');
	assertOptionalColor(params.color, 'color');

	const r = resolve(params);
	validateNonNegative(r.distance, 'distance');
	validateNonNegative(r.intensity, 'intensity');

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Clamp to the documented range: `samples: Math.min(64, Math.max(1, Math.round(v)))`.
2. If you need a longer streak, raise `distance` or `intensity` instead of `samples` — both raise cost more gracefully.
3. Omit the prop entirely to use the default of 32, which is tuned for quality/perf.
4. Check any Studio Visual Mode slider binding isn't exceeding the schema's `max`.

Example fix

// before
lightTrail({ samples: Math.round(pixelsOfStreak / 2) });

// after
lightTrail({ samples: Math.min(64, Math.max(1, Math.round(pixelsOfStreak / 2))) });

const MAX_SAMPLES = 64;
const safeSamples = (v: unknown): number | undefined => {
  if (v === undefined) return undefined;
  if (typeof v !== 'number' || !Number.isFinite(v)) {
    throw new TypeError('samples must be a finite number');
  }
  return Math.min(MAX_SAMPLES, Math.max(1, Math.round(v)));
};
const samples = safeSamples(userSamples);
lightTrail(samples === undefined ? {} : { samples });

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

When it happens

Trigger: Calling `lightTrail({samples: 65})` or any integer > 64. Values 1..64 are accepted; integers below 1 throw error 680; non-integers throw the integer-guard error first.

Common situations: Slider/expression returning large numbers (e.g. an unbounded `interpolate`); porting a config from a different effect with a higher cap; assuming 'more samples = better' and cranking it past 64; multiplying samples by devicePixelRatio.

Related errors

• "samples" must be >= 1, but got ${samples}
• The "width" and "height" props must be numbers on <Img> when
• The ${formatPropList(conflictingProps)} prop${conflictingPro
• <Solid>: `pixelDensity` must be a positive finite number. Re
• "${name}" must be greater than 0, but got ${JSON.stringify(v

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