remotion-dev/remotion · error · TypeError

${effectLabel} effect requires a parameters object, but got

Error message

${effectLabel} effect requires a parameters object, but got ${JSON.stringify(params)}

What it means

Thrown by the shared assertEffectParamsObject validator when an effect's params argument is null, undefined, a primitive, or any non-object value. Nearly every @remotion/effects effect calls this as its first validation step, so the effectLabel in the message identifies which effect was misused. The check uses typeof !== 'object' plus an explicit null guard because typeof null === 'object'.

Source

Thrown at packages/effects/src/validate-effect-param.ts:6

export const assertEffectParamsObject = (
	params: unknown,
	effectLabel: string,
): void => {
	if (params === null || typeof params !== 'object') {
		throw new TypeError(
			`${effectLabel} effect requires a parameters object, but got ${JSON.stringify(params)}`,
		);
	}
};

export const assertRequiredFiniteNumber = (
	value: unknown,
	name: string,
): void => {
	if (typeof value !== 'number' || !Number.isFinite(value)) {
		throw new TypeError(
			`"${name}" must be a finite number, but got ${JSON.stringify(value)}`,
		);
	}
};

export const assertRequiredColor = (value: unknown, name: string): void => {
	if (typeof value !== 'string' || value.length === 0) {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Wrap params in an object: vibrance({amount: 0.5}) not vibrance(0.5)
If params may be undefined from upstream code, default to an empty object: effect(params ?? {})
Check the effect's TypeScript type definition (e.g. VibranceParams) and ensure your call site matches the readonly object shape
Add a runtime guard before calling the effect if consuming untrusted data

Example fix

// before
const e = vibrance(0.5);

// after
const e = vibrance({amount: 0.5});

Defensive patterns

Strategy: validation

Validate before calling

function isValidEffectParams(value: unknown): boolean {
  return value !== null && typeof value === 'object';
}

// Before calling the effect:
if (!isValidEffectParams(params)) {
  throw new Error(`Expected params object, got ${typeof params}`);
}
const e = vibrance(params as VibranceParams);

Type guard

function isEffectParams(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === 'object';
}

Prevention

Always wrap effect params in an object literal: effect({key: value})
Let TypeScript guide you — the effect's param type (e.g. VibranceParams) is an object type, not a primitive
When consuming untrusted data, validate with isEffectParams before passing to the effect
Default to an empty object if params may be absent: effect(params ?? {})

When it happens

Trigger: Calling an effect factory with a non-object argument: vibrance(0.5) instead of vibrance({amount: 0.5}), or tvSignalOff(null), or venetianBlinds('vertical'), or passing undefined because the caller forgot the object wrapper entirely.

Common situations: Developer assumes the effect takes positional arguments instead of a params object; data flows from an untyped API or JSON parse where the shape is unknown; a refactor changed the effect signature and old call sites were not updated; serialization/deserialization produced null instead of {}.

Related errors

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