What causes "Argument passed to "${api}" for param "${param}" is undefined" in remotion-dev/remotion?

Inspect the stack trace to find which `api` and `param` are named in the message, then trace that argument back to its source and ensure it is a number before the call.

remotion-dev/remotion · error · TypeError

Argument passed to "${api}" for param "${param}" is undefine

Error message

Argument passed to "${api}" for param "${param}" is undefined

What it means

Thrown by the runtime `checkNumber` validator inside the transform helpers (matrix, matrix3d, perspective, rotate, scale, skew, skewX, skewY, translate, translate3d) when a numeric argument is literally `undefined`. The library double-checks at runtime because the public overloads are declared with `...args: unknown[]`, so TypeScript cannot guarantee callers pass real numbers. It fires on the first `undefined` argument it encounters.

Source

Thrown at packages/animation-utils/src/transformation-helpers/make-transform/transform-functions.ts:27

	LengthUnit,
	LengthUnitString,
} from '../../type';
import {angleUnits, lengthPercentageUnits, lengthUnits} from '../../type';
import {isUnitWithString} from './is-unit-with-string';

/* Matrix transformation */

const checkNumber = ({
	num,
	param,
	api,
}: {
	num: unknown;
	param: string;
	api: string;
}) => {
	if (typeof num === 'undefined') {
		throw new TypeError(
			`Argument passed to "${api}" for param "${param}" is undefined`,
		);
	}

	if (typeof num !== 'number') {
		throw new TypeError(
			`Argument passed to "${api}" for param "${param}" is ${JSON.stringify(
				num,
			)}`,
		);
	}

	if (!Number.isFinite(num)) {
		throw new TypeError(
			`Argument passed to "${api}" for param "${param}" is ${JSON.stringify(
				num,
			)} (must be finite)`,
		);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Inspect the stack trace to find which `api` and `param` are named in the message, then trace that argument back to its source and ensure it is a number before the call.
Default the value at the call site: `translate(x ?? 0)` or guard with `if (typeof x === 'number')`.
Remove any `as any` / `as number` casts on the offending argument so TypeScript catches the undefined path at compile time.
If the value is genuinely optional, branch your animation so the transform helper is only called when the value exists.

Example fix

// before
const tx = props.offsetX; // possibly undefined
const t = translate(tx);

// after
const tx = props.offsetX;
if (typeof tx !== 'number') {
  throw new Error('props.offsetX is required');
}
const t = translate(tx);

Defensive patterns

Strategy: type-guard

Validate before calling

// Before calling any transform helper, confirm the value is a number.
const assertTransformNumber = (v: unknown, name: string): number => {
  if (typeof v !== 'number') {
    throw new Error(`Transform param ${name} is not a number (got ${v})`);
  }
  return v;
};
// usage: translate(assertTransformNumber(rawX, 'x'))

Type guard

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

// usage
if (isTransformNumber(rawX)) {
  translate(rawX);
} else {
  // handle missing value
}

Prevention

Type every value passed to a transform helper as `number` (or the matching unit-string type) so TypeScript rejects undefined at compile time.
Avoid `as any` / `as number` casts on transform arguments.
Validate data from untyped boundaries (APIs, JSON, props) with a typeof guard before animating.
Default optional animation values with `?? 0` only when 0 is a sensible transform value.

When it happens

Trigger: Calling any transform helper with an `undefined` value, e.g. `translate(undefined)`, `rotate(missingProp)`, `skew(someObj.notSet)`, or passing fewer positional args than an overload needs after a type assertion (`translate(x as any)` where x is undefined). Also triggered from plain JavaScript (no TS checks) where an unset variable slips through.

Common situations: Reading a value from an API response, props object, or interpolated animation array that is optional and was never filled in; destructuring a config object with a missing key; passing the result of `arr[i]` where the index is out of range; migrating from a loose-typed codebase into the typed transform helpers.

Related errors

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