remotion-dev/remotion · error · TypeError

"amplitude" must be >= 0, but got ${JSON.stringify(resolved.

Error message

"amplitude" must be >= 0, but got ${JSON.stringify(resolved.amplitude)}

What it means

TypeError thrown by wave's validateWaveParams when the resolved amplitude is less than 0. Validation runs after the numeric finiteness check, so it only fires for a finite number outside the allowed range. Note the comparison uses the resolved value, so it also catches the case where amplitude is omitted... actually the default is 60, so it only triggers when an explicit negative number is passed.

Source

Thrown at packages/effects/src/wave/index.ts:103

const validateWaveParams = (params: WaveParams): void => {
	assertEffectParamsObject(params, 'Wave');
	assertOptionalFiniteNumber(params.phase, 'phase');
	assertOptionalFiniteNumber(params.amplitude, 'amplitude');
	assertOptionalFiniteNumber(params.wavelength, 'wavelength');

	if (
		params.direction !== undefined &&
		params.direction !== 'horizontal' &&
		params.direction !== 'vertical'
	) {
		throw new TypeError(
			`"direction" must be "horizontal" or "vertical", but got ${JSON.stringify(params.direction)}`,
		);
	}

	const resolved = resolve(params);
	if (resolved.amplitude < 0) {
		throw new TypeError(
			`"amplitude" must be >= 0, but got ${JSON.stringify(resolved.amplitude)}`,
		);
	}

	if (resolved.wavelength <= 0) {
		throw new TypeError(
			`"wavelength" must be > 0, but got ${JSON.stringify(resolved.wavelength)}`,
		);
	}
};

// Sine wave warp: displaces source UVs along the propagation axis. WebGL2 only.
export const wave = createEffect<WaveParams, WaveState>({
	type: 'dev.remotion.effects.wave',
	label: 'wave()',
	documentationLink: 'https://www.remotion.dev/docs/effects/wave',
	backend: 'webgl2',
	calculateKey: (params) => {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass amplitude >= 0 (use Math.max(0, value) for derived values).
Clamp frame-driven amplitude with Math.abs() or Math.max(0, x) before passing it.
If you want 'no wave', use amplitude: 0 rather than a negative number.
Type amplitude as a non-negative number and assert it at the source.

Example fix

// before - interpolated amplitude dips below zero
const e = wave({amplitude: Math.sin(frame / 10) * 100}); // negative half the time

// after - clamp to the valid range
const e = wave({amplitude: Math.max(0, Math.sin(frame / 10) * 100)});

Defensive patterns

Strategy: validation

Validate before calling

import {wave} from '@remotion/effects';

const clampAmplitude = (value: number): number => {
  if (!Number.isFinite(value)) {
    throw new TypeError(`amplitude must be a finite number, got ${value}`);
  }
  return Math.max(0, value);
};

const amplitude = clampAmplitude(rawAmplitude);
const e = wave({amplitude, wavelength: 240});

Type guard

const isNonNegativeFinite = (v: unknown): v is number =>
  typeof v === 'number' && Number.isFinite(v) && v >= 0;

Try / catch

try {
  const e = wave({amplitude: rawAmplitude, wavelength: 240});
} catch (err) {
  if (err instanceof TypeError) {
    console.error('Invalid wave amplitude:', rawAmplitude, err);
  }
  throw err;
}

Prevention

Clamp frame-derived amplitude with Math.max(0, value) before passing it.
Use amplitude: 0 to flatten the wave instead of a negative value.
Type amplitude as number and assert non-negativity at the source of derived values.
Watch interpolation/easing curves that can dip below zero.

When it happens

Trigger: Calling wave({amplitude: -10}) or passing a computed value that goes negative (e.g. amplitude derived from a frame-based formula that dips below zero). assertOptionalFiniteNumber runs first, so non-numbers/NaN/Infinity are rejected earlier with a different message.

Common situations: Animation formulas that interpolate amplitude across frames and accidentally go negative; sign errors in derived values; passing a value intended for a different effect.

Related errors

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