DEV Community

Oleg Sidorkin
Oleg Sidorkin

Posted on

Fix 'SharedArrayBuffer is not defined': a practical guide to cross-origin isolation

#security #webdev #javascript #tutorial

If you've ever seen this in the console:

Uncaught ReferenceError: SharedArrayBuffer is not defined
Enter fullscreen mode Exit fullscreen mode

or your multithreaded WebAssembly quietly fell back to a single thread, the cause is almost always the same thing: your page is not cross-origin isolated. Here's what that means, why the browser does it, and exactly how to fix it.

TL;DR

Send these two headers on the response for the document that loads your code:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Enter fullscreen mode Exit fullscreen mode

Then confirm in the console:

console.log(self.crossOriginIsolated) // should be true
Enter fullscreen mode Exit fullscreen mode

When it's true, SharedArrayBuffer is available and Wasm threads work. The rest of this post is the why, the gotchas, and how to verify it without writing code.

Why the browser blocks SharedArrayBuffer

SharedArrayBuffer lets multiple threads share memory, which is what makes multithreaded WebAssembly possible. But shared memory also enables very high-precision timers, and those make Spectre-style side-channel attacks easier. After Spectre, browsers pulled SharedArrayBuffer and only give it back when your page proves it isn't sharing a process with untrusted cross-origin content. That proof is cross-origin isolation.

A page becomes cross-origin isolated when it sends both:

  • Cross-Origin-Opener-Policy: same-origin — cuts the link to other top-level windows so your page gets its own browsing context group.
  • Cross-Origin-Embedder-Policy: require-corp — says every subresource must explicitly opt in to being loaded by you.

With both in place, the browser flips self.crossOriginIsolated to true and restores SharedArrayBuffer.

The mistake almost everyone makes: CORP is not COEP

This one burns a lot of people. There's a third, similarly named header:

Cross-Origin-Resource-Policy: cross-origin
Enter fullscreen mode Exit fullscreen mode

Cross-Origin-Resource-Policy (CORP) is set by a subresource (an image, a script, a font) to declare who is allowed to embed it. It does not isolate your document. If you set CORP on your HTML page expecting SharedArrayBuffer to show up, nothing happens, because that's not what CORP does.

The two headers that isolate the page are COOP and COEP. CORP comes into play only as a way for your subresources to satisfy COEP (more on that below). Keep them straight:

  • COOP + COEP → set on your document, turn isolation on.
  • CORP → set on subresources, lets them keep loading once COEP is on.

Check whether you're actually isolated

One line in the console:

self.crossOriginIsolated // true once COOP + COEP are correct
Enter fullscreen mode Exit fullscreen mode

If it's false, the headers aren't reaching the page. The two usual reasons:

  1. Wrong origin. You set the headers on a CDN subdomain, but not on the origin actually serving index.html. Isolation is decided by the document's own response headers.
  2. Host strips them. Some static hosts (GitHub Pages and friends) don't let you set custom response headers at all, so they never arrive.

Setting the headers

nginx:

add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Embedder-Policy "require-corp" always;
Enter fullscreen mode Exit fullscreen mode

Express:

app.use((req, res, next) => {
  res.set('Cross-Origin-Opener-Policy', 'same-origin')
  res.set('Cross-Origin-Embedder-Policy', 'require-corp')
  next()
})
Enter fullscreen mode Exit fullscreen mode

Can't control the headers (GitHub Pages, itch.io, some CDNs): use a service-worker shim like coi-serviceworker, which injects the headers client-side. It's how a lot of Godot and Unity web exports get threads working on hosts that won't set headers for you.

The side effect to plan for

Once COEP: require-corp is on, every cross-origin subresource has to opt in, or the browser refuses to load it. Each third-party image, script, or font now needs either:

  • Cross-Origin-Resource-Policy: cross-origin (or same-site) on its own response, or
  • proper CORS (Access-Control-Allow-Origin) plus a crossorigin attribute on the tag.

So turning on isolation can break third-party assets until you fix them. If a CDN you use won't send CORP/CORS, you'll need to proxy or self-host those files. This is the part that turns a "two header" change into an afternoon, so budget for it.

Verify any URL without writing code

To save the back-and-forth, I built a small free tool that fetches a URL's response headers and tells you whether it's actually cross-origin isolated, with the COOP/COEP values and the CORP-vs-COEP gotcha called out:

Cross-Origin Isolation Checker

There's also a longer, copy-paste walkthrough with server configs for more setups here:

Enable Wasm threads (SharedArrayBuffer) with COOP/COEP

Recap

  1. SharedArrayBuffer is gated behind cross-origin isolation (a post-Spectre security move).
  2. Isolate the page with COOP: same-origin + COEP: require-corp on the document.
  3. CORP is a different header for subresources, it does not isolate your page.
  4. Confirm with self.crossOriginIsolated === true.
  5. Expect to fix cross-origin subresources that COEP now blocks.

Get those right and SharedArrayBuffer, and your Wasm threads, come back.

Top comments (2)

Collapse
 
alexshev profile image
Alex Shev •

The practical gotcha with cross-origin isolation is usually the third-party asset chain.

Teams add COOP/COEP on the app shell, see crossOriginIsolated still false, and then discover one script, iframe, font, or CDN response is missing the right policy. The headers are simple; making every dependency compatible is the real checklist.

Collapse
 
osidorkin profile image
Oleg Sidorkin • • Edited

Exactly, the headers are the easy part. One nuance: with COEP: require-corp, a non-compliant resource gets blocked (COEP error in the console), it doesn't flip crossOriginIsolated back to false. If isolation is still false after both headers, it's usually COOP/COEP not landing on the document itself. Tip: roll out with Cross-Origin-Embedder-Policy-Report-Only first to see what'll break, and COEP: credentialless drops the CORP requirement for third-party assets you don't control (Chromium/Firefox, check support if you need Safari).