[Bug] Marker crashes with "appendChild" error during rapid client-side navigation (React 19 / Next.js 16)

[ak800i]

Description

The Marker component crashes with Cannot read properties of undefined (reading 'appendChild') during rapid client-side navigation (e.g., quickly navigating between a random page and a page that contains a <Map> with <Marker> children).

Expected Behavior

No response

Steps to Reproduce

TL:DR steps to reproduce:

Quickly navigate back and forth between pages which contain a <Map> with <Marker> children.

Steps to Reproduce

1. Create a Next.js 16 app with React 19
2. Page A: a list page (no map)
3. Page B: a detail page with containing children
4. Navigate rapidly between Page A and Page B using client-side navigation (clicking links, not full page loads)
5. After a few rapid back-and-forth navigations, the error appears

Root Cause

The Marker component's useEffect at marker.ts#L86 calls marker.addTo(map.getMap()) with [] deps. During rapid unmount/remount cycles in React 19, the new mount's useEffect can fire before the previous mount's cleanup has run. At that point, mapbox-gl's Map instance still exists but its internal DOM container sub-elements have been torn down, causing marker.addTo() to fail when it tries to appendChild into a destroyed container.

Through instrumentation, I confirmed:

• map.getMap() returns a valid Map instance (truthy)
• map._container exists (truthy)
• But inside marker.addTo(), deeper container child elements are undefined
• The error is intermittent and depends on navigation speed

Suggested Fix

Wrap marker.addTo(map.getMap()) in a try-catch in the useEffect

useEffect(() => {
    try {
        marker.addTo(map.getMap());
    } catch {
        // Map container was destroyed during rapid navigation — safe to ignore
        return;
    }
    return () => {
        marker.remove();
    };
}, []);

Environment

• react-map-gl: 8.1.0 (via @vis.gl/react-mapbox)
• mapbox-gl: 3.11.0
• React: 19.1.0
• Next.js: 16.2.2 (App Router, Turbopack)
• Browser: Chrome

Logs

No response