remotion-dev/remotion · error · TypeError

separateVideoLayers() expects an options object.

Error message

separateVideoLayers() expects an options object.

What it means

validateOptions is the entry guard for separateVideoLayers(): if the single options argument is missing or not an object (null, undefined, a primitive, an array), the function cannot read src/outputs from it, so a TypeError is thrown instead of failing later mid-separation.

Source

Thrown at packages/video-matting/src/separate-video-layers.ts:157

			typeof WritableStream === 'undefined' ||
			!(output.outputWritable instanceof WritableStream)
		) {
			throw new TypeError(
				`outputs.${layer}.outputWritable must be a WritableStream.`,
			);
		}

		if (output.outputWritable.locked) {
			throw new TypeError(
				`outputs.${layer}.outputWritable must not already be locked.`,
			);
		}
	}
};

const validateOptions = (options: SeparateVideoLayersOptions) => {
	if (!options || typeof options !== 'object') {
		throw new TypeError('separateVideoLayers() expects an options object.');
	}

	const isBlob = typeof Blob !== 'undefined' && options.src instanceof Blob;
	const isUrl = options.src instanceof URL;
	if (typeof options.src !== 'string' && !isUrl && !isBlob) {
		throw new TypeError('src must be a string, URL, or Blob.');
	}

	if (typeof options.src === 'string' && options.src.length === 0) {
		throw new TypeError('src must not be an empty string.');
	}

	if (
		options.outputs !== undefined &&
		(!options.outputs ||
			typeof options.outputs !== 'object' ||
			Array.isArray(options.outputs))
	) {

View on GitHub (pinned to b2f4e34732)

Solutions

1. Call with an object: separateVideoLayers({ src, outputs })
2. Check the calling code for a missing/spread argument
3. Add a default parameter or guard at the call site

Example fix

// before
await separateVideoLayers('video.mp4', { base: {...} });
// after
await separateVideoLayers({ src: 'video.mp4', outputs: { base: {...} } });

if (options == null || typeof options !== 'object') throw new TypeError('separateVideoLayers requires an options object');

const isOptionsObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);

try { await separateVideoLayers(arg); } catch (e) { if (e instanceof TypeError && e.message.includes('expects an options object')) { /* rebuild options */ } else throw e; }

When it happens

Trigger: Calling separateVideoLayers() with no arguments; passing null; accidentally passing (src, outputs) positionally; spreading gone wrong so the argument is undefined.

Common situations: Migrating from an imagined positional API; destructuring results incorrectly; TypeScript unchecked dynamic calls (awaiting user-supplied config).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Emoji ${emoji} not found. Available emojis: ${emojis.map((e)
• The start and end values must be of the same type. Start val
• Non-animatable values cannot be interpolated. Start value: $
• The units of the start and end values must match. Start valu
• The start and end values must have the same structure. Start

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/f038f769863c18d1. Report an issue: GitHub.