remotion-dev/remotion · error · TypeError

src must not be an empty string.

Error message

src must not be an empty string.

What it means

validateOptions for separateVideoLayers() rejects an empty-string src: passing '' as the source path/URL cannot resolve to a video file, so the guard fails fast with a TypeError before any processing begins.

Source

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

				`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))
	) {
		throw new TypeError('outputs must be an object.');
	}

	validateLayerOutputOptions({
		layer: 'base',
		output: options.outputs?.base,
	});
	validateLayerOutputOptions({
		layer: 'foreground',
		output: options.outputs?.foreground,

View on GitHub (pinned to b2f4e34732)

Solutions

1. Provide a real path/URL string for src
2. Guard at the call site: throw or skip when src is empty
3. Fix the upstream source of the empty string (form field, env var, URL param)

Example fix

// before
const src = process.env.VIDEO_PATH ?? '';
await separateVideoLayers({ src });
// after
const src = process.env.VIDEO_PATH;
if (!src) throw new Error('VIDEO_PATH is not set');
await separateVideoLayers({ src });

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

const isNonEmptyString = (v) => typeof v === 'string' && v.trim().length > 0;

try { await separateVideoLayers({ src }); } catch (e) { if (e instanceof TypeError && e.message.includes('empty string')) { /* supply a real path */ } else throw e; }

When it happens

Trigger: Passing src: '' from an uninitialized variable, an empty form field, or a template literal whose interpolation is empty.

Common situations: Config files where the video path key exists but has an empty value; URL params missing so `params.get('src')` returns '' after `?? ''`; joining paths with an undefined base.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• No src passed
• The `<OffthreadVideo>` tag requires a string for `src`, but
• No `src` was passed to <OffthreadVideo>.
• No src passed
• No `src` was passed to <Audio>.

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