avajs/ava · error · Error

Shared workers can be used only when worker threads are enab

Error message

Shared workers can be used only when worker threads are enabled

What it means

AVA's shared worker registration API (registerSharedWorker in lib/worker/plugin.js) requires Node.js worker_threads, which AVA disables in certain execution modes. When the resolved AVA options have workerThreads set to a falsy value, calling registerSharedWorker immediately throws this Error. AVA disables worker threads when running in environments where they cannot be used, most commonly when the precompile/`node:` worker mode is off or under test concurrency settings that force in-process execution.

Source

Thrown at lib/worker/plugin.js:95

			return publishMessage(data);
		},

		async * subscribe() {
			yield * receiveMessages();
		},
	};
}

export function registerSharedWorker({
	filename,
	initialData,
	supportedProtocols,
	teardown,
}) {
	const options_ = getOptions();

	if (!options_.workerThreads) {
		throw new Error('Shared workers can be used only when worker threads are enabled');
	}

	if (!supportedProtocols.includes('ava-4')) {
		throw new Error(`This version of AVA (${pkg.version}) does not support any of the desired shared worker protocols: ${supportedProtocols.join(',')}`);
	}

	filename = String(filename); // Allow URL instances.

	let worker = workers.get(filename);
	if (worker === undefined) {
		worker = createSharedWorker(filename, initialData, async () => {
			// Run possibly asynchronous teardown functions serially, in reverse
			// order. Any error will crash the worker.
			const teardownFns = workerTeardownFns.get(worker);
			if (teardownFns !== undefined) {
				for await (const fn of [...teardownFns].toReversed()) {
					await fn();
				}

View on GitHub (pinned to bbfd946322)

Solutions

Enable worker threads for AVA (upgrade to a modern AVA version where worker_threads is on by default, and remove any config that disables it).
Verify the runtime supports worker_threads: require('node:worker_threads') in the same Node version AVA uses; upgrade Node.js if it is missing.
If worker threads genuinely cannot be enabled, remove the shared worker and communicate via another mechanism (files, a local server) instead of t.registerSharedWorker().

Example fix

// before
test('share state', t => {
  t.registerSharedWorker({ filename: './my-worker.js', supportedProtocols: ['ava-4'] });
});

// after — ensure AVA runs with worker threads enabled (modern AVA default)
// ava.config.js: no `workerThreads: false`; Node >= 12; then register as before

Defensive patterns

Strategy: validation

Validate before calling

import { worker_threads as hasWorkerThreads } from 'node:process';
// or: const hasWorkerThreads = (() => { try { require('node:worker_threads'); return true; } catch { return false; } })();
if (!hasWorkerThreads) {
  console.warn('Skipping shared-worker registration: worker threads unavailable');
} else {
  t.registerSharedWorker({ filename, supportedProtocols: ['ava-4'] });
}

Prevention

Only use shared workers on modern Node.js (>=12.11) where worker_threads are stable.
Never set workerThreads: false in AVA config if shared workers are used.
Feature-detect worker_threads availability in CI before enabling shared-worker tests.

When it happens

Trigger: Calling t.registerSharedWorker() (which reaches registerSharedWorker) from a test file while AVA was configured or forced to run without worker threads — e.g. running AVA with worker threads disabled via configuration, or in an environment where worker_threads are unavailable/unsupported.

Common situations: Running AVA on a Node.js build without worker thread support, using a config that disables worker threads (older AVA defaults or CI constraints), running tests in restricted containers/runtimes where worker_threads are blocked, or using shared workers with AVA versions/modes that predate worker-thread-based test execution.

Related errors

AI-assisted analysis of avajs/ava@bbfd946322 (2026-09-02). Data as JSON: /api/errors/498ee73076d5f7e5. Report an issue: GitHub.