remotion-dev/remotion · error · TypeError

Argument passed to "${api}" for param "${param}" is ${JSON.s

Error message

Argument passed to "${api}" for param "${param}" is ${JSON.stringify(num)}

What it means

Second branch of `checkNumber`: the argument is defined but is not a `number` (e.g. a string that is not a unit string, a boolean, an object, null). The message embeds `JSON.stringify(num)` so the offending value is shown verbatim. It is a runtime guard for the `...args: unknown[]` implementation of every transform helper.

Source

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

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

function matrix(
	a: number,
	b: number,

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Read the `JSON.stringify`-ed value in the message to see exactly what was passed, then convert it: `Number(value)` if it is a numeric string, or use the unit-string overload (`'10px'`) where supported.
2. For numeric strings from config, coerce explicitly before calling: `translate(Number(raw.x))`.
3. If you meant to pass a CSS unit string, switch to the overload that accepts it (e.g. `translate('10px')` instead of `translate(10, 'px')` mismatched with another number).
4. Add a typeof guard at the boundary that produces the value.

Example fix

// before
const t = translate(rawX); // rawX is "100" from JSON

// after
const t = translate(Number(rawX));

// Coerce or reject non-numbers before calling transform helpers.
const asTransformNumber = (v: unknown): number => {
  if (typeof v === 'number') return v;
  if (typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v))) {
    return Number(v);
  }
  throw new Error(`Expected a number, got ${JSON.stringify(v)}`);
};
// usage: translate(asTransformNumber(rawX))

const isLengthUnitString = (v: unknown): v is string =>
  typeof v === 'string' && /^-?\d*\.?\d+(px|em|rem|vw|vh|%)$/.test(v);

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

When it happens

Trigger: Passing a non-numeric, non-unit value where a number is expected: `translate('abc')` (a plain string that fails `isUnitWithString`), `rotate(true)`, `scale(null)`, `skew({})`, or `perspective('5')` without a unit suffix. Also `translate(5, 'px')` is valid but `translate(5, 5)` is fine whereas `translate('5', 5)` fails the unit check.

Common situations: Treating the helpers like CSS string builders and passing raw CSS strings (`'10px'`) into a slot that expects a unit string in a different overload; untyped data from JSON/config where numbers arrive as strings; boolean coercion bugs (`translate(flag)`).

Related errors

• Argument passed to "${api}" for param "${param}" is undefine
• Argument passed to "${api}" for param "${param}" is ${JSON.s
• skew() supports only the following signatures: skew(angle: A
• translate() supports only the following signatures: translat
• translate3d() supports only the following signatures: transl

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