[4.0.0-next.3] CDN wasmPaths breaks local dev servers (CORS Worker construction error)

[AdrianBesleaga]

System Info

• @huggingface/transformers@4.0.0-next.3
• onnxruntime-web@1.25.0-dev
• Vite 7.3.1
• Chrome (latest)
• macOS

Environment/Platform

• Website/web-app
• Browser extension
• Server-side (e.g., Node.js, Deno, Bun)
• Desktop app (e.g., Electron)
• Other (e.g., VSCode extension)

Description

In v4, backends/onnx.js unconditionally sets wasmPaths to cdn.jsdelivr.net:

onnxEnv.wasm.wasmPaths = `https://cdn.jsdelivr.net/npm/onnxruntime-web@${ORT_VERSION}/dist/`;

This causes onnxruntime-web to construct Workers from CDN URLs, which browsers block with a CORS error when the page is served from localhost (or any non-CDN origin):

Failed to construct 'Worker': Script at 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.25.0-dev/dist/ort-wasm-simd-threaded.asyncify.mjs'
cannot be accessed from origin 'http://localhost:5175'.

Additionally, even when serving the ORT files locally, the COEP requirement (Cross-Origin-Embedder-Policy: require-corp) for SharedArrayBuffer means ALL sub-resources need proper Cross-Origin-Resource-Policy headers — which CDN-served files don't have in a local dev context.

v3 behavior (worked correctly)

v3.x did not set wasmPaths, allowing onnxruntime-web to resolve WASM files and Worker scripts relative to the importing script. Bundlers like Vite serve these naturally from localhost, so everything was same-origin — no CORS issues.

Suggested Fix

Only default to CDN wasmPaths if the user hasn't already configured a custom path and the environment isn't a local dev server:

// Only default to CDN if user hasn't overridden and not on localhost
if (!onnxEnv.wasm.wasmPaths) {
    const isLocalDev = typeof location !== 'undefined' &&
        (location.hostname === 'localhost' || location.hostname === '127.0.0.1');
    if (!isLocalDev) {
        onnxEnv.wasm.wasmPaths = `https://cdn.jsdelivr.net/npm/onnxruntime-web@${ORT_VERSION}/dist/`;
    }
}

Or, better yet: revert to v3 behavior and let onnxruntime-web resolve paths naturally. Only use CDN as an explicit opt-in via env.backends.onnx.wasm.wasmPaths.

Current Workaround

Override wasmPaths after import and serve ORT dist files locally (e.g., via vite-plugin-static-copy):

import { env } from '@huggingface/transformers';

// Point to locally-served ORT files instead of CDN
env.backends.onnx.wasm.wasmPaths = '/ort/';

Vite config (using vite-plugin-static-copy):

import { viteStaticCopy } from 'vite-plugin-static-copy';

// Also need cross-origin isolation headers for SharedArrayBuffer
function crossOriginIsolation() {
    return {
        name: 'cross-origin-isolation',
        configureServer(server) {
            server.middlewares.use((_req, res, next) => {
                res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
                res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
                res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
                next();
            });
        },
    };
}

export default defineConfig({
    plugins: [
        crossOriginIsolation(),
        viteStaticCopy({
            targets: [{ src: '<path-to-onnxruntime-web>/dist/*', dest: 'ort' }],
        }),
    ],
});

Reproduction

1. Create a Vite project
2. Install @huggingface/transformers@4.0.0-next.3
3. In a Web Worker, run:

import { AutoModelForVision2Seq, env } from '@huggingface/transformers';

env.allowLocalModels = false;
env.useBrowserCache = true;

const model = await AutoModelForVision2Seq.from_pretrained(
    'HuggingFaceTB/SmolVLM-500M-Instruct',
    { dtype: 'q4f16', device: 'webgpu' }
);

4. Browser console shows: Failed to construct 'Worker' CORS error

[xenova]

Hi there 👋 Thanks for the report. v3 also had similar logic for deciding when to load from CDN or not:

transformers.js/packages/transformers/src/backends/onnx.js

Lines 275 to 294 in a1c658a

	// (Optional) Set path to wasm files. This will override the default path search behavior of onnxruntime-web.
	// By default, we only do this if we are not in a service worker and the wasmPaths are not already set.
	if (
	// @ts-ignore Cannot find name 'ServiceWorkerGlobalScope'.ts(2304)
	!(typeof ServiceWorkerGlobalScope !== 'undefined' && self instanceof ServiceWorkerGlobalScope) &&
	ONNX_ENV.versions?.web &&
	!ONNX_ENV.wasm.wasmPaths
	) {
	const wasmPathPrefix = `https://cdn.jsdelivr.net/npm/onnxruntime-web@${ONNX_ENV.versions.web}/dist/`;
	ONNX_ENV.wasm.wasmPaths = apis.IS_SAFARI
	? {
	mjs: `${wasmPathPrefix}ort-wasm-simd-threaded.mjs`,
	wasm: `${wasmPathPrefix}ort-wasm-simd-threaded.wasm`,
	}
	: {
	mjs: `${wasmPathPrefix}ort-wasm-simd-threaded.asyncify.mjs`,
	wasm: `${wasmPathPrefix}ort-wasm-simd-threaded.asyncify.wasm`,
	};
	}

Maybe @fs-eire knows what your error originates from.

[fs-eire]

I tried the steps but I cannot reproduce the issue.

Vite v6:

Vite v7:

Do you mind giving a more detailed reproduce steps in case I missed anything?

[fs-eire]

By the way, I think consuming from CDN is the default behavior of transformers.js.

If you don't like this default behavior, set like this:

env.backends.onnx.wasm.wasmPaths = undefined;  // not set to '/ort/'

Should make it automatically work with Vite dev server without explicit copy.

[AdrianBesleaga]

@fs-eire @xenova , Thank you for the quick answer.

In v4, backends/onnx.js sets wasmPaths to cdn.jsdelivr.net by default. This works fine on its own — but when the page has COEP headers (Cross-Origin-Embedder-Policy: require-corp), browsers block all cross-origin resources that lack a Cross-Origin-Resource-Policy header, including the CDN-served ORT Worker script.

COEP headers are required for SharedArrayBuffer, which ONNX Runtime itself needs for multi-threaded WASM execution. So the conflict is:

ORT needs SharedArrayBuffer → requires COEP headers
COEP blocks cross-origin resources without CORP headers
v4 defaults wasmPaths to CDN → CDN files are cross-origin
💥 Worker construction fails

https://github.com/AdrianBesleaga/transformers.js-cors-bug-reproduced

[fs-eire]

Confirmed that the problem is caused by wasmLoadPromise(). It works on my side while skip calling wasmLoadPromise().

The implementation also introduced other bug like #1532.

[nico-martin]

@AdrianBesleaga thank you so much for looking into it and open an issue!
I explained here wha we added the new way of fetching the wasm factory.

And if I understand you correctly, it is mainly the blobUrl that causes problems together with the COEP headers, right?

I added a new check that does not use the blob caching if COEP headers are set. Does that solve your problem?
https://github.com/huggingface/transformers.js/blob/v4-loadWasmFactory-fix/packages/transformers/src/backends/utils/cacheWasm.js#L80-L86

[AdrianBesleaga]

Hello @nico-martin , thank you for working on it.

Tested the v4-loadWasmFactory-fix branch (commit 41a6ca7) using the reproduction repo.

The original CORS error (Failed to construct 'Worker') is gone ✅, but a new error appears:

no available backend found. ERR: [wasm] TypeError: Failed to construct 'URL': Invalid URL
What's happening:

canUseBlobURLs()
correctly detects crossOriginIsolated === true and returns false. But then

loadWasmFactory()
just returns the original CDN URL unchanged (line 135). ORT still receives a cross-origin URL and fails to load it under COEP.

Reproduction branch: test-v4-loadWasmFactory-fix (vendors the built fix branch)

https://github.com/AdrianBesleaga/transformers.js-cors-bug-reproduced/tree/test-v4-loadWasmFactory-fix

[nico-martin]

@AdrianBesleaga, thanks for tring my fix!

Is there any way you can find out where the “TypeError: Failed to construct ‘URL’: Invalid URL” is occurring? I assume it's here: https://github.com/microsoft/onnxruntime/blob/main/js/web/lib/wasm/wasm-factory.ts#L204

Could you also make sure that no “old” files are being used? It's best to delete everything in Chrome DevTools under “Application --> Cache Storage” to ensure that no cached versions find their way into the app.

[nico-martin]

Ok, I think I found it. The canUseBlobURLs works as expected. But ONNX Runtime does the blob conversion.

If you take a look here, isMultiThreaded is true because SharedArrayBuffer is available and the factoty (.mjs file) is served from a different origin. Therefore it preloads the file and passes the blob: https://github.com/microsoft/onnxruntime/blob/main/js/web/lib/wasm/wasm-utils-import.ts#L301

This logic has not been changed for two years. Can you confirm that your problem only occurred with v4 and that it works with v3? If it works with v3, could you check where it loads the factory (.mjs) from?

[AdrianBesleaga]

@nico-martin

Confirmed: v3 works ✅ with COEP headers, v4 does not ❌.

Tested with identical setup — same Vite config with COEP headers (Cross-Origin-Embedder-Policy: require-corp), same model (Xenova/distilbert-base-uncased-finetuned-sst-2-english), device: 'wasm':

Where v3 loads the factory from: v3 also sets wasmPaths to CDN (https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.8.1/dist/). However, in v3's ORT (1.22), importWasmModule uses the embeddedWasmModule path — it checks embeddedWasmModule && scriptSrc && isSameOrigin(scriptSrc), and since Vite serves the script from localhost (same-origin), it uses the embedded module directly and never hits the CDN preload() path.

In v4's ORT (1.25), importWasmModule has an additional isWasmOverridden parameter and more conditions around the embedded module, which causes it to fall through to the CDN path — where preload() (fetch + createObjectURL) fails under COEP because the CDN lacks Cross-Origin-Resource-Policy headers.

Also worth noting: v3 imports onnxruntime-web (factory: ort-wasm-simd-threaded.jsep.mjs), while v4 imports onnxruntime-web/webgpu (factory: ort-wasm-simd-threaded.asyncify.mjs).

v3 — works ✅

git clone -b test-v3-comparison https://github.com/AdrianBesleaga/transformers.js-cors-bug-reproduced
cd transformers.js-cors-bug-reproduced && npm install && npm run dev

v4 fix branch — still broken ❌

git clone -b test-v4-loadWasmFactory-fix https://github.com/AdrianBesleaga/transformers.js-cors-bug-reproduced
cd transformers.js-cors-bug-reproduced && npm install && npm run dev