remotion-dev/remotion · error

Unsupported protocol

Error message

Unsupported protocol

What it means

Remotion Studio's element-library protocol handler accepts a URL supplied by the client, parses it, and only forwards requests whose protocol is http: or https:. Any other scheme (file:, ftp:, data:, chrome:, etc.) is rejected with this error and converted into an 'invalid-url' studio protocol error response. This is a deliberate security guard to stop the Studio server from being used as a proxy to arbitrary protocols or local files.

Source

Thrown at packages/studio-server/src/preview-server/studio-protocol/handle-element-library.ts:92

	}

	const parsedRequest =
		StudioProtocolInternals.parseStudioProtocolAddElementLibraryRequest(body);
	if (parsedRequest === null) {
		writeStudioProtocolError({
			code: 'unsupported-protocol',
			message: 'Invalid Remotion Studio Protocol request.',
			response,
			status: 400,
		});
		return;
	}

	let normalizedUrl: string;
	try {
		const parsedUrl = new URL(parsedRequest.url);
		if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
			throw new Error('Unsupported protocol');
		}

		normalizedUrl = parsedUrl.href;
	} catch {
		writeStudioProtocolError({
			code: 'invalid-url',
			message: 'The Element catalog URL must be an absolute HTTP or HTTPS URL.',
			response,
			status: 400,
		});
		return;
	}

	const displayName = parsedRequest.displayName?.trim() ?? null;
	if (displayName === '') {
		writeStudioProtocolError({
			code: 'invalid-display-name',
			message: 'The Element catalog display name must not be empty.',

View on GitHub (pinned to a6a7485a9a)

Solutions

1. Serve the element library over HTTP(S): run a local server (npx serve, python -m http.server) and use 'http://localhost:PORT/lib.json' instead of a file: path
2. Fix the protocol typo or scheme so the URL starts with 'http://' or 'https://'
3. Check the studio config/CLI flag supplying the element-library URL and correct it
4. If the resource is local, proxy it through the Remotion Studio public/ folder or an existing dev server

Example fix

// before
fetch('file:///home/me/library.json')
// after
fetch('http://localhost:8080/library.json')

function isHttpUrl(url: string): boolean {
  try {
    const u = new URL(url);
    return u.protocol === 'http:' || u.protocol === 'https:';
  } catch {
    return false;
  }
}
if (!isHttpUrl(libraryUrl)) throw new Error(`Element library URL must be http(s): ${libraryUrl}`);

function isHttpUrl(url: string): url is `http://${string}` | `https://${string}` {
  try {
    const u = new URL(url);
    return u.protocol === 'http:' || u.protocol === 'https:';
  } catch {
    return false;
  }
}

try {
  await requestLibrary(url);
} catch (err) {
  if (err instanceof Error && (err.message === 'Unsupported protocol' || isInvalidUrlProtocolError(err))) {
    console.error('Use an http:// or https:// URL, not ' + new URL(url).protocol);
  } else throw err;
}

When it happens

Trigger: Calling the studio element-library endpoint with a URL whose scheme is not http/https, e.g. 'file:///home/user/icons.json', 'ftp://host/lib', or a URL string that fails URL parsing entirely; also a misconfigured element library source in studio config that points at a non-http location.

Common situations: Developers pointing the element library at a local file path instead of a local HTTP server; copying a data: or blob: URL from the browser; typos like 'htt://localhost:3000' that make URL parsing fail and fall into the same catch block.

Related errors

• Studio server port should be a number. Got ${typeof port} ($
• Studio server port should be a number between 1 and 65535. G
• "cloudRunUrl" parameter must be a string, but is ${JSON.stri
• The value "${path}" is already prefixed with the static base
• Only HTTP(S) URLs can be imported

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