remotion-dev/remotion · error · TypeError

onModelLoadProgress must be a function.

Error message

onModelLoadProgress must be a function.

What it means

separateVideoLayers validates its options before doing any work. If you pass onModelLoadProgress and it is not a function (and not undefined), a TypeError is thrown immediately during option validation. This callback is supposed to receive model download/loading progress (0-1), so anything other than a callable would silently break progress reporting, hence the strict check.

Solutions

  1. Remove the onModelLoadProgress property entirely if you don't need progress reporting (undefined is allowed).
  2. Pass an actual function, e.g. (progress) => console.log(progress).
  3. If the value comes from user config, default it: onModelLoadProgress: cfg.cb ?? undefined, and reject non-function config values before calling.

Example fix

// before
await separateVideoLayers({src, onModelLoadProgress: null});
// after
await separateVideoLayers({
  src,
  onModelLoadProgress: (progress) => setProgress(progress),
});
Defensive patterns

Strategy: validation

Validate before calling

if (opts.onModelLoadProgress !== undefined && typeof opts.onModelLoadProgress !== 'function') {
  throw new TypeError('onModelLoadProgress must be a function or undefined');
}

Type guard

const isProgressCb = (v: unknown): v is (p: number) => void =>
  typeof v === 'function';

Prevention

When it happens

Trigger: Calling separateVideoLayers({src, onModelLoadProgress: <non-function>}) — e.g. onModelLoadProgress: true, a string, a number, or null (null is not undefined, so it fails the check).

Common situations: Passing null intending 'no callback'; passing a promise-returning value or a config object instead of the callback; typo like onModelLoadProgres leaving a stale value; reading the option from untyped config/JSON input.

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@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/62af9477ba76ea5f. Report an issue: GitHub.

Appendix: source

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

			options.keyframeIntervalInSeconds <= 0)
	) {
		throw new TypeError(
			'keyframeIntervalInSeconds must be a positive finite number.',
		);
	}

	if (
		options.onProgress !== undefined &&
		typeof options.onProgress !== 'function'
	) {
		throw new TypeError('onProgress must be a function.');
	}

	if (
		options.onModelLoadProgress !== undefined &&
		typeof options.onModelLoadProgress !== 'function'
	) {
		throw new TypeError('onModelLoadProgress must be a function.');
	}
};

const makeInput = (src: string | URL | Blob): Input => {
	const source =
		typeof src === 'string' || src instanceof URL
			? new UrlSource(src)
			: new BlobSource(src);

	return new Input({formats: ALL_FORMATS, source});
};

const probeVideoInput = async ({
	input,
	videoQuality,
}: {
	input: Input;
	videoQuality: Quality;

View on GitHub (pinned to b2f4e34732)