Troubleshooting

The worker did not answer. The usual causes:

• The method name does not exist in the worker. The worker throws, and the error goes to onWorkerError.
• The method uses onMessage().handle(...) and never calls resolve, reject or cancel.
• The worker failed to start. Check the browser console for an error loading the worker file.

Add onWorkerError to the configuration while you debug:

createWorker<MyWorker>(source, {
  onWorkerError: (error) => console.error(error.message),
});

A cancellation is a message, and a worker in the middle of a synchronous loop cannot receive messages. Break the work into chunks and pause between them, or restart the worker with unwrap(worker).cancelAll(reason, { force: true }). See Cancellation and progress.

A worker created from a function cannot use anything from the surrounding file: only the text of the function travels. Define what it needs inside the function, pass it as a payload, or use primitiveParameters. See Runtime workers.

The payload, or the result, contains something that cannot cross threads: a function, a DOM node, a class instance with methods, or a buffer that was already transferred. Send plain data, and convert on the other side.

The worker file is not being built. A plain new URL('./x.worker.ts', import.meta.url) passed to createWorker is copied as an asset, without being compiled. Use the form your bundler detects:

• Vite: import workerUrl from './x.worker?worker&url'.
• webpack 5, Parcel, Vite: new Worker(new URL('./x.worker.ts', import.meta.url), { type: 'module' }).

See Creating workers.

The worker file uses import or export, so it must be started as a module. Pass workerOptions: { type: 'module' }.

It was transferred. A transfer moves the memory to the other thread and leaves the sender with a buffer of length 0. Read what you need before the call, or use the buffer that comes back. See Transferable objects.

With maxWorkers above 1, each Worker has its own memory, and consecutive calls can land on different Workers. Keep stateful workers as a single Worker. State is also lost after reboot, after force, and when idle Workers are terminated with keepAlive: false.

reboot and force need a source the library can start again: a URL, a string or a function. A native Worker you created yourself cannot be restarted by the library. Create a new one and pass it to a new createWorker.