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

If you've ever seen this in the console:

Uncaught ReferenceError: SharedArrayBuffer is not defined

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

Then confirm in the console:

console.log(self.crossOriginIsolated) // should be true

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

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

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;

Express:

app.use((req, res, next) => {

  res.set('Cross-Origin-Opener-Policy', 'same-origin')

  res.set('Cross-Origin-Embedder-Policy', 'require-corp')

  next()

})

Can't control the headers (GitHub Pages, itch.io, some CDNs): use a service-worker shim like

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.