remotion-dev/remotion · error · TypeError

"direction" must be "horizontal" or "vertical", but got ${JS

Error message

"direction" must be "horizontal" or "vertical", but got ${JSON.stringify(params.direction)}

What it means

TypeError thrown by wave's validateWaveParams when params.direction is defined but is neither 'horizontal' nor 'vertical'. Validation runs synchronously when wave() is called; the offending value is echoed via JSON.stringify. direction is optional, so undefined is accepted and defaults to 'horizontal'.

Source

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

	if (value === undefined) {
		return;
	}

	assertRequiredFiniteNumber(value, name);
};

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)}`,
		);
	}
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Use exactly 'horizontal' or 'vertical', or omit direction to use the default.
If the value is dynamic, validate it against ['horizontal','vertical'] before passing it.
Type direction as the WaveDirection union so the compiler rejects invalid literals.
Search the codebase for the misspelled value and fix it at the source.

Example fix

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

const e = wave({direction: 'diagonal', amplitude: 60}); // throws TypeError

// after
const e = wave({direction: 'horizontal', amplitude: 60});
// or omit for the default
const e2 = wave({amplitude: 60});

Defensive patterns

Strategy: validation

Validate before calling

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

const WAVE_DIRECTIONS = ['horizontal', 'vertical'] as const;
type WaveDirection = (typeof WAVE_DIRECTIONS)[number];

const assertDirection = (direction: unknown): WaveDirection | undefined => {
  if (direction === undefined) return undefined;
  if (!WAVE_DIRECTIONS.includes(direction as WaveDirection)) {
    throw new TypeError(`direction must be one of ${WAVE_DIRECTIONS.join('|')}, got ${JSON.stringify(direction)}`);
  }
  return direction as WaveDirection;
};

const direction = assertDirection(config.direction);
const e = wave({direction, amplitude: 60});

Type guard

const WAVE_DIRECTIONS = ['horizontal', 'vertical'] as const;
type WaveDirection = (typeof WAVE_DIRECTIONS)[number];
const isWaveDirection = (v: unknown): v is WaveDirection =>
  typeof v === 'string' && (WAVE_DIRECTIONS as readonly string[]).includes(v);

Try / catch

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

Prevention

Type direction as the literal union 'horizontal' | 'vertical'.
Validate dynamic/API-supplied direction against the allowed set before calling wave().
Avoid shorthand ('h'/'v') and free-form user input without a whitelist.
Run typecheck in CI to catch misspelled literals.

When it happens

Trigger: Calling wave({direction: 'Horizontal'}) (wrong case), wave({direction: 'h'}), wave({direction: 'diagonal'}), wave({direction: 0}), or passing a variable that holds an unexpected value. The check is skipped only when direction is undefined.

Common situations: Case typos; shorthand values ('h'/'v'); data-driven direction from an API/config without validation; copying a direction name from another effect library.

Related errors

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