Running Transformers.js in a Web Worker means moving inputs and results across postMessage, which uses structured cloning. Two of the library's types do not survive it. A Tensor fails outright with #<_Tensor> could not be cloned. A RawImage clones, but arrives as a plain object with no methods, and the pipeline rejects it.
Why
Structured cloning copies own data properties and drops prototypes. A Tensor's data and dims are getters on the prototype, reading from an internal ONNX Runtime tensor object, and structured cloning refuses the whole object. A RawImage keeps its pixels in own properties, so those arrive, but the class is gone.
The fix: send plain data, rebuild on the other side
import { RawImage } from "@huggingface/transformers";
// Page: an image becomes typed-array pixels plus its shape.
const payload = {
data: image.data.slice(), // a copy: the page may still be showing it
width: image.width,
height: image.height,
channels: image.channels,
};
worker.postMessage(payload, [payload.data.buffer]);
// Worker: rebuild the class before calling the pipeline.
const input = new RawImage(payload.data, payload.width, payload.height, payload.channels);
// Worker: flatten any Tensor in the result before posting it back.
const flat = { data: tensor.data, dims: tensor.dims, type: tensor.type };
self.postMessage(flat, [flat.data.buffer]);Results can nest tensors, as depth estimation does with its predicted_depth, so walk the result and flatten every Tensor before posting, rather than handling one known field.
Copy or transfer?
Transferring a buffer is free, but it detaches the buffer on the sending side. If the page is still showing the image it just sent, the preview goes blank. If the same recording is sent twice, the second send has nothing to send. Copy by default, and transfer only data you will not touch again, such as a webcam frame already drawn.
Audio has the same trap in a quieter form. Transferring a clip's Float32Array to the worker is the fast path, and it leaves the page holding an array of length zero. Nothing fails on the first run. The second run, after the user changes a setting and presses the button again, sends an empty clip. The fix is to decode once, keep that array on the page, and hand each run its own copy with samples.slice(). A copy of a few seconds of 16 kHz audio is a few hundred kilobytes, far cheaper than decoding the file again.
Why your tests did not catch it
A unit test usually replaces the worker with a function call that passes objects by reference, so nothing is cloned. A mocked end-to-end run loads no weights, so no real Tensor is produced. On this site the depth page was the first to return a tensor, and only a real model load showed the error. If you test a worker with a harness, make the harness call structuredClone(message, { transfer }) the way postMessage does.
Pages on this site that send images to a worker this way: depth estimation, image classification and image embeddings. The first and last also get tensors back.