remotion-dev/remotion · error · Error

"Worker" is not available. Cannot call parseMediaOnWebWorker

Error message

"Worker" is not available. Cannot call parseMediaOnWebWorker()

What it means

Thrown by parseMediaOnWebWorker when the global Worker constructor is undefined. The web worker entry instantiates new Worker(new URL('./worker-web-entry.mjs', import.meta.url)); without a global Worker (Node without worker support, test sandboxes, or environments that strip workers) it aborts before creation.

Source

Thrown at packages/media-parser/src/worker.module.ts:21

import {parseMediaOnWorkerImplementation} from './parse-media-on-worker-entry';

export {
	hasBeenAborted,
	ImageType,
	IsAnImageError,
	IsAnUnsupportedFileTypeError,
	IsAPdfError,
	MediaParserAbortError,
} from './errors';
export type {ParseMediaOnWorker, ParseMediaOnWorkerOptions} from './options';

export const parseMediaOnWebWorker: ParseMediaOnWorker = <
	F extends Options<ParseMediaFields>,
>(
	params: ParseMediaOnWorkerOptions<F>,
) => {
	if (typeof Worker === 'undefined') {
		throw new Error(
			'"Worker" is not available. Cannot call parseMediaOnWebWorker()',
		);
	}

	if (import.meta.url.includes('.vite/deps')) {
		const err = [
			'Detected Vite pre-bundling, which will break the worker.',
			'Please add the following to your vite.config.js:',
			'  optimizeDeps: {',
			'    exclude: ["@remotion/media-parser/worker"]',
			'  }',
		].join('\n');
		throw new Error(err);
	}

	const worker = new Worker(new URL('./worker-web-entry.mjs', import.meta.url));

	return parseMediaOnWorkerImplementation(

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Call parseMediaOnWebWorker only in a real browser context where Worker exists.
On the server, use parseMediaOnServerWorker or in-process parseMedia instead.
If a Worker polyfill is needed in tests, configure jsdom/happy-dom or run the test in a real browser environment.

Example fix

// before
import { parseMediaOnWebWorker } from '@remotion/media-parser/worker';
await parseMediaOnWebWorker(opts); // in Node test

// after
import { parseMedia } from '@remotion/media-parser';
await parseMedia(opts); // works without Worker

Defensive patterns

Strategy: fallback

Validate before calling

if (typeof Worker === 'undefined') throw new Error('parseMediaOnWebWorker requires a browser Worker');
await parseMediaOnWebWorker(opts);

Type guard

const hasBrowserWorker = () => typeof Worker !== 'undefined' && typeof window !== 'undefined';

Try / catch

try { return await parseMediaOnWebWorker(opts); } catch (e) { if (/"Worker" is not available/.test(String((e as Error).message))) { const { parseMedia } = await import('@remotion/media-parser'); return parseMedia(opts); } else throw e; }

Prevention

Call parseMediaOnWebWorker only in real browser contexts.
Use parseMediaOnServerWorker or parseMedia on the server.
Configure test environments to provide a Worker polyfill or skip the web-worker path.

When it happens

Trigger: Calling parseMediaOnWebWorker in a non-browser runtime lacking global Worker, or in a browser build that polyfilled Worker away. The guard fires prior to any worker construction.

Common situations: Running browser-targeted code under Node in a test runner without a Worker polyfill. SSR/edge environments. Older bundler outputs that exclude the worker constructor. Confusing server worker vs web worker entry points.

Related errors

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/1ae06a102333ed7e. Report an issue: GitHub.