RSC navigation causes "Cannot read properties of null (reading 'removeChild')" error with React portals

[sasagar]

Description

During client-side navigation (using useRouter or browser back/forward), a "Cannot read properties of null (reading 'removeChild')" error occurs in React's commit
phase. This happens when the page contains React components that use portals (e.g., react-aria-components modals, popovers).

Environment

• Waku version: 1.0.0-alpha.3
• React version: 19.2.4
• Browser: Chrome, Safari, Firefox (all affected)
• OS: macOS, Windows, Linux (all affected)

Steps to Reproduce

1. Create a page with React Aria components (Dialog, Modal, Popover, etc.)
2. Navigate to that page using Waku's router
3. Use window.history.back() or browser back button to navigate away
4. Observe console error

Error Message

Uncaught TypeError: Cannot read properties of null (reading 'removeChild')
    at Ar (index.js:98848)
    at Tl (index.js:100732)
    at Or (index.js:105427)
    ...

Root Cause Analysis

Through debugging, I identified the following:

1. Waku renders RSC content into a <span> element directly in document.body (observed as body > span with ~40+ children, no id/class attributes)
2. During SPA navigation, React attempts to clean up portal references
3. The portal container reference becomes null before React's cleanup completes, causing null.removeChild(child) to fail

Debug Evidence

// DOM state before navigation:
document.body.children[2] = <span> with 42 children (Waku RSC container)
document.body.children[5] = <div class="app-content">...</div>
document.body.children[6] = <script id="_R_">__WAKU_HYDRATE...</script>

The error occurs immediately after popstate event, during React's commit phase (commitDeletionEffects → removeChild).

Current Workaround

I replaced SPA navigation with full page navigation for back button:

// Instead of:
window.history.back();

// I use:
window.location.href = previousPath;

This bypasses the RSC cleanup issue by doing a full page reload.

Expected Behavior

Client-side navigation should complete without errors when pages contain React portal-based components.

Possible Causes

1. RSC container lifecycle not properly synchronized with React's portal cleanup
2. Race condition between navigation state update and portal unmounting
3. Container reference becoming stale during the navigation transition

Related Context

• This is similar in nature to unmount an empty component is breaking with ReactDOM portals facebook/react#14811 (portal unmount issues), but the root cause appears to be in Waku's RSC lifecycle management
• Race condition in router #1880 (Router race condition) may be related

Additional Information

• The error is suppressed and navigation "works" but only because I catch the error globally
• Using react-aria-components, but likely affects any library using React portals
• The issue does NOT occur with full page navigation, only SPA transitions

---

Happy to provide more debugging information or a minimal reproduction repository if helpful.

[dai-shi]

Thanks for reporting this. I'm not sure if #1880 is related to this, but I think we should fix #1880 first, as we have #1896.
Meanwhile, if you can, creating a minimal test case (like #1896) with portals would be helpful.

[nihgwu]

I see this issue randomly when navigating

[dai-shi]

I see this issue randomly when navigating

randomly? interesting.

I hope to start working on router issues soon-ish.

[dai-shi]

It doesn't seem to reproduce this error even with Waku version: 1.0.0-alpha.3.
Could someone try?