Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

attachShadow throws NotSupportedError inside a React component

ErrorShadow root cannot be created on a host which already hosts a shadow tree

Short answer

A host element can only get one shadow root made with attachShadow. React in development mounts effects twice and may call ref callbacks twice, so your attachShadow call runs twice on the same element and the second call throws. Reuse host.shadowRoot when it exists instead of calling attachShadow again.

  • Applies to React 19, Chrome, Firefox
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the host already has a shadow root at the moment the code runs. If it prints a ShadowRoot, a second attachShadow call is the bug.

    // inside your effect or ref callback, before attachShadow
    console.log(host.shadowRoot);
  2. 2Match what you see, then jump to its fix

    1. 1The error appears only in development, and the page works in a production buildStrict Mode runs the effect twice on the same elementFix
    2. 2The error repeats on every render, or fails on the first mountattachShadow is called in a ref callback or in the component bodyFix
    3. 3The error appears in production too, on an element you did not createAnother script already attached a shadow root to the elementFix

What does the error look like?

  • Shadow root cannot be created on a host which already hosts a shadow tree
  • NotSupportedError

Cause 1 of 3

Strict Mode runs the effect twice on the same element

1Check

In development with StrictMode, React runs one extra setup, cleanup, setup cycle for every Effect. The element stays the same, but a shadow root cannot be removed, so the second setup hits an element that already has one.

grep -rn "attachShadow" src/

2Fix

Make the setup safe to run twice: take the existing shadow root if there is one.

useEffect(() => {
  const host = hostRef.current;
  const root = host.shadowRoot ?? host.attachShadow({ mode: 'open' });
  // render or append into root
}, []);

3Verify

Reload the page in development and watch the console.

// no NotSupportedError appears in the browser console

Confirmed by react.dev

Did this fix it?

Cause 2 of 3

attachShadow is called in a ref callback or in the component body

1Check

Strict Mode also calls component bodies twice and runs an extra setup and cleanup cycle for every callback ref. Anything in those places must be safe to repeat.

grep -rn "ref={" src/ | grep -i shadow

2Fix

Keep the same guard in the callback, and keep side effects out of the render body.

<div
  ref={(node) => {
    if (node && !node.shadowRoot) {
      node.attachShadow({ mode: 'open' });
    }
  }}
/>

3Verify

Render the component twice, for example by toggling it, and confirm no error.

// toggle the component on and off in the page

Confirmed by react.dev

Did this fix it?

Cause 3 of 3

Another script already attached a shadow root to the element

1Check

attachShadow throws NotSupportedError for any element that already has a shadow root created from JavaScript, no matter who created it.

// browser console
document.querySelector('#host').shadowRoot

2Fix

Use a host element of your own, or read the existing shadowRoot instead of attaching again.

const root = host.shadowRoot ?? host.attachShadow({ mode: 'open' });

3Verify

Reload the page; the call no longer throws.

// no error in the console

Confirmed by developer.mozilla.org

Did this fix it?

How do I stop it coming back?

  • Write every attachShadow call as host.shadowRoot ?? host.attachShadow(...).
  • Keep StrictMode on in development; it is what exposes this bug.
  • Do not use a ref flag to skip the second run; make the code correct when it runs again.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.