Cross-Origin Isolation in Production: Why credentialless, and the Header That Silently Killed Every Worker

If you want better results with cross-origin isolation coep credentialless, this guide explains the practical steps, common mistakes, and useful browser-based tools that make the process easier.

Two headers stand between your WebAssembly and its threads: Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy.

Without them, window.crossOriginIsolated is false, SharedArrayBuffer does not exist, and onnxruntime-web asks for twelve threads, receives one, and prints a console notice instead of an error.

On our background remover, a 1200 by 1200 cut-out took 15,659 ms that way. With the headers, the same image took 9,518 ms and produced a byte-identical result.

That is the whole prize: 39 percent, for two response headers.

Quick Takeaways

• Focus first on credentialless, not require-corp — and why the choice is forced.
• Apply the steps from this guide to improve cross-origin isolation coep credentialless without overcomplicating the workflow.
• Use Background Remover to turn this advice into action directly in your browser.
• Read We Benchmarked Two Background Removal AI Models. Neither One Wins. if you want a related guide that expands on the same topic.

The companion benchmark post covers the numbers. This one covers everything that happened while shipping the headers, because COEP is the most fragile header we have ever put in front of users:

there are two variants and one of them breaks ten tools, the scope you choose decides whether payment iframes die, workers created under COEP need the header themselves or fail with an error message that is literally empty,

and one Next.js route pattern that looks like it covers two directories covers neither.

credentialless, Not require-corp — and Why the Choice Is Forced

COEP has two variants: require-corp and credentialless. Both make the document cross-origin isolated. They differ in what they demand of every cross-origin subresource the page loads.

• require-corp: every cross-origin subresource must carry a Cross-Origin-Resource-Policy header, or the load is blocked. The CDN has to cooperate.
• credentialless: cross-origin no-CORS requests are sent WITHOUT credentials, and most CDNs serve them happily. No cooperation needed.

Our tools import ES modules at runtime from esm.sh, jsDelivr and cdn.jsdelivr — the HQ image codecs, pptxgenjs, fontkit, OCR engines, imagetracerjs. Google Fonts serves stylesheets.

Three analytics beacons POST to their own hosts. Under require-corp, every one of those loads needs a CORP header from a server we do not control,

and esm.sh does not send one. require-corp would have broken ten tools to buy the same isolation credentialless buys for free.

Scope It to the Pages That Need It

If you would rather do this step in the browser than by hand, Image Upscaler handles it without a signup.

COEP also blocks cross-origin IFRAMES that do not opt in with a CORP or credentialless header of their own. Audit your site for cross-origin iframes before you pick a scope.

We have two kinds: the blog's YouTube and Vimeo embeds, and the Razorpay and PayPal frames on the donation page.

None of those appear under /tool, so that is where the headers go: COOP same-origin plus COEP credentialless on /tool/:path* only. The blog, the homepage and the donation page keep their iframes and their non-isolated context.

The widest scope that cannot break payment is narrower than the whole site — this is one of the rare cases where shipping less header is what makes the change safe.

The Soft Navigation Limit Nobody Mentions

Cross-origin isolation is a property of the DOCUMENT, and in an App Router site a client-side navigation does not load a new document.

A visitor who lands on the homepage and clicks through to a tool stays in the homepage's non-isolated context: the headers were on the tool URL, but no new document was fetched,

so crossOriginIsolated stays false and the WASM runtime runs single-threaded.

Only a direct load or a refresh of a tool URL gets threads. We measured this rather than assuming it, and the reading code checks crossOriginIsolated at runtime rather than assuming either way —

that is the correct posture for every consumer: read the flag, degrade to single-threaded, never promise threads the document did not get.

Trap: A Worker Under COEP Dies With an EMPTY Error Message

PDF to Excel is the quickest way to apply what this section describes to your own file.

This is the one that cost a day. A dedicated worker created from a COEP document must ITSELF be delivered with a compatible COEP header.

If it is not, the browser refuses the worker — and fires an ErrorEvent with an empty message, no filename and no line number. The script still answers 200.

No CSP violation fires. There is nothing anywhere pointing at the cause.

• The failure is invisible twice over: the worker code never runs, and the error it dies with carries no information.
• One of our workers failed silently and the tool STILL WORKED, because the library fell back to the main thread — multi-second inference on the UI thread, which is the exact Page Unresponsive freeze the worker existed to prevent.

We proved the cause by elimination: the identical worker, created from a page without COEP, replied ok. Created from a /tool page, it died with the empty ErrorEvent.

The fix was to add COEP to the worker scripts themselves: the bundler's worker chunks under /_next/static, and the unbundled ones in /workers.

COEP on a plain script subresource is inert for every other consumer of those paths, so the header is safe to add unconditionally.

Trap: The Route Pattern That Looks Right and Matches Nothing

The natural Next.js headers config for covering both worker locations is one source with an alternation: /:path(_next/static|workers)/:rest*. It looks like it matches /_next/static/* and /workers/*. It does not match either.

A route parameter in Next's header source matches a single path SEGMENT, so :path can never consume _next/static — the slash between them is the boundary the parameter cannot cross.

We shipped the alternation, and the result was that /workers carried the header while every bundler chunk under /_next/static did not, so the Turbopack workers stayed broken while the config looked present.

The Verification That Matters

There is more detail in Migrating pdf.js 3 to 5: The Breaking Changes Nobody Warns You About once you have the basics here.

Headers in config are not headers in production. Three checks, all cheap, all runnable in a browser console on a deployed tool page:

• window.crossOriginIsolated === true, and typeof SharedArrayBuffer !== 'undefined'.
• The WASM runtime's thread count is honored: onnxruntime-web prints a console notice when it is not.
• A dedicated worker created from the page replies — construct it from both a tool page and a non-tool page, and compare. The empty ErrorEvent is the signature of the worker-COEP trap.

We run the first two in the deployment verification checklist against the live box, per tool surface. The third is only ever discovered by the silent main-thread fallback, which is why it belongs in a checklist rather than in a postmortem.

Conclusion

Cross-origin isolation is the highest-leverage two headers you can add to a WASM-heavy site — 39 percent on real work, for configuration.

But the margins are full of silent failures: the wrong variant breaks tools that never touch WASM, the wrong scope breaks payment, the missing worker header fails with an error message that is empty by specification,

and the route pattern that reads correctly matches nothing. Every one of those shipped green through a pipeline with type checks, lint, unit tests and a bundle budget, because none of them look at response headers or worker lifecycles.

The verification that catches them is a curl and a browser console, run against the deployed box, listed in a checklist that runs on every deploy.

The easiest way to improve cross-origin isolation coep credentialless is to follow a repeatable checklist, test the result, and use the right tool for the specific task instead of forcing one workflow on every use case.

For official background, standards, or platform guidance, review web.dev guide to cross-origin isolation.