remotion-dev/remotion · error · TypeError

initialProps must be null or an object containing…

Error message

initialProps must be null or an object containing JSON-compatible values with valid JSX attribute names

What it means

createElementPayload validates its input via assertCreateElementPayloadInput; this TypeError is thrown when initialProps is neither null nor an object whose values are JSON-compatible and whose keys are valid JSX attribute names. It guarantees the generated Element's props can be rendered as static JSX attributes.

Solutions

Pass initialProps: null when there are no initial props
Ensure initialProps is a plain object with string values that JSON-serialize cleanly
Use keys that are valid JSX attribute names (letters/digits, camelCase, no special characters)
Validate/sanitize props before calling createElementPayload

Example fix

// before
createElementPayload({..., initialProps: {onClick: () => {}, 'data-x.y': 1}});
// after
createElementPayload({..., initialProps: {volume: 0.5, loop: true}});

Defensive patterns

Strategy: validation

Validate before calling

const isValidAttrName = (k: string) => /^[a-zA-Z][a-zA-Z0-9]*$/.test(k);
const valid = (p: unknown): boolean =>
  p === null || (typeof p === 'object' && !Array.isArray(p) &&
    Object.entries(p as Record<string, unknown>).every(([k, v]) =>
      isValidAttrName(k) && (v === null || ['string','number','boolean'].includes(typeof v))));
if (!valid(initialProps)) throw new Error('initialProps must be null or JSON-compatible with valid JSX attribute names');

Type guard

const isElementInitialProps = (v: unknown): v is Record<string, string | number | boolean | null> | null =>
  v === null || (typeof v === 'object' && v !== null && !Array.isArray(v) &&
    Object.entries(v).every(([k, val]) => /^[a-zA-Z][a-zA-Z0-9]*$/.test(k) && (val === null || ['string','number','boolean'].includes(typeof val))));

Try / catch

try {
  const payload = createElementPayload(input);
} catch (e) {
  if (e instanceof TypeError && e.message.startsWith('initialProps must be null or an object')) {
    return createElementPayload({...input, initialProps: sanitizeInitialProps(input.initialProps)});
  }
  throw e;
}

Prevention

Pass null instead of omitting or using non-object initialProps
Strip functions, undefined, and nested objects that don't JSON-serialize
Use camelCase JSX-safe prop names

When it happens

Trigger: Calling createElementPayload with initialProps set to a non-object (string, number, array, boolean), an object containing functions, symbols, undefined, or nested non-JSON values, or keys that are not valid JSX attribute names (e.g. containing dots, dashes-invalid or reserved characters).

Common situations: Programmatic Element payload creation where callers pass runtime prop values (callbacks, class instances) or accidentally omit null-coalescing for absent props; also raw API/scripted payload construction bypassing Studio's UI validation.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of remotion-dev/remotion@46a3a6bf13 (2026-09-18). Data as JSON: /api/errors/45972e33100c6419. Report an issue: GitHub.

Appendix: source

Thrown at packages/studio-protocol/src/element-payload.ts:97

	}

	if (!isDuration(input.durationInFrames))
		throw new TypeError(
			'durationInFrames must be an integer between 1 and 100000000',
		);
	if (
		input.installationMode !== undefined &&
		input.installationMode !== 'wrapped' &&
		input.installationMode !== 'component-owned-sequence'
	) {
		throw new TypeError(
			'installationMode must be "wrapped" or "component-owned-sequence"',
		);
	}

	const initialProps = input.initialProps ?? null;
	if (!isElementInitialProps(initialProps)) {
		throw new TypeError(
			'initialProps must be null or an object containing JSON-compatible values with valid JSX attribute names',
		);
	}

	if (
		!hasValidElementInitialPropsForInstallationMode({
			initialProps,
			installationMode: input.installationMode,
		})
	) {
		throw new TypeError(
			'component-owned-sequence initialProps must not define from, durationInFrames, or name, and style must be an object when provided',
		);
	}
};

export const createElementPayload = (
	input: CreateElementPayloadInput,

View on GitHub (pinned to 46a3a6bf13)