remotion-dev/remotion · error · Error

Config.addElementLibrary() expects an absolute URL, got ${JS

Error message

Config.addElementLibrary() expects an absolute URL, got ${JSON.stringify(url)}

What it means

The url option must be an absolute URL parseable by the URL constructor. Relative paths or malformed strings (missing scheme, stray characters) fail parsing and throw.

Source

Thrown at packages/cli/src/config/element-libraries.ts:33

	) {
		const receivedType = Array.isArray(options) ? 'an array' : typeof options;
		throw new Error(
			`Config.addElementLibrary() expects an object, got ${receivedType}`,
		);
	}

	const {url, displayName} = options;
	if (typeof url !== 'string') {
		throw new Error(
			`Config.addElementLibrary() expects "url" to be a string, got ${typeof url}`,
		);
	}

	let parsedUrl: URL;
	try {
		parsedUrl = new URL(url);
	} catch {
		throw new Error(
			`Config.addElementLibrary() expects an absolute URL, got ${JSON.stringify(url)}`,
		);
	}

	if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
		throw new Error(
			`Config.addElementLibrary() only supports HTTP and HTTPS URLs, got ${JSON.stringify(url)}`,
		);
	}

	if (displayName !== undefined && typeof displayName !== 'string') {
		throw new Error(
			`Config.addElementLibrary() expects the display name to be a string, got ${typeof displayName}`,
		);
	}

	const trimmedDisplayName = displayName?.trim() ?? null;
	if (trimmedDisplayName === '') {

View on GitHub (pinned to 8f97758157)

Solutions

Prefix the URL with the scheme, e.g. https://example.com/library.json
Log the url value right before the call to spot malformed template output

Example fix

// before
Config.addElementLibrary({url: 'example.com/library.json'});

// after
Config.addElementLibrary({url: 'https://example.com/library.json'});

Defensive patterns

Strategy: validation

Validate before calling

try { new URL(url); } catch { /* not absolute; prepend scheme */ }

Type guard

const isAbsoluteUrl = (u: string) => { try { new URL(u); return true; } catch { return false; } };

Prevention

Always use fully-qualified https URLs in config
Test config parsing in a unit test

When it happens

Trigger: Passing 'example.com/library.json', '/library.json', or a string with invalid URL characters to Config.addElementLibrary().

Common situations: Using a relative path instead of https://..., or a template string that produced undefined/empty segments.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of remotion-dev/remotion@8f97758157 (2026-08-28). Data as JSON: /api/errors/042d44e93d0e858d. Report an issue: GitHub.