· 10 min read
Suspense BoundaryMissed a State Update:4s Black ScreenA Suspense boundary missed a state update and stalled every deep link for 4s. The fix: wrap only the suspending leaf, or read store state after subscribe().

A Suspense boundary can make a component miss a state update without any error. The component is not slow and it does not re-render wrongly. It simply was not mounted when the update happened. I hit this on a single-page WebGL site with scene-per-URL deep links. Deep links sometimes stayed black for four seconds, then the scene appeared all at once with no reveal animation. The cause was a font. This post covers how I found it, why the symptom pointed straight at the cause once I read it correctly, and two fixes: move the boundary down, or make the subscriber read current state.
The symptom: black for exactly four seconds
The site is one shared WebGL canvas. Each URL opens a different scene, and a transition layer covers the swap with a shutter animation. When you open a non-home URL directly, the boot sequence is roughly:
- Load the assets for that scene.
- Prewarm the GPU (upload textures, compile shaders) behind a cover.
- Set the transition status
warming → leaving. The cover reacts to this and plays its exit. - When the cover finishes, set
leaving → entering → idle, and the scene reveals.
The bad runs looked like this. The screen stayed black, then the scene appeared with no shutter and no reveal. The home URL was never affected. The problem was intermittent, and it was worse on slow CPUs.
I measured it on production at 4x CPU throttle, with 16 runs across 8 deep links. 16 of 16 runs had a leaving → entering gap of 4,000 ms. The scene was visible at 5.3 to 7.5 seconds.
A gap of exactly 4,000 ms in every run is not a performance problem. Performance gives you a spread. A fixed number is a timeout. The transition system had a fail-open watchdog: if a transition does not complete in 4 seconds, force it through so that the user never gets stuck. That watchdog was doing all the work. It forced finishLeave and finishEnter while the cover slices were still parked off-screen, so you got no animation, only a hard cut.
So the real question was not "what is slow". It was "who was supposed to drive the leaving edge forward, and why was it absent?"
Why the Suspense boundary missed a state update
The transition layer holds every cover variant: the boot cover, the shutter, and a variant with a text label. The text label uses drei's <Text>, which renders with troika and, per the drei Text docs, "will suspend while loading the font data".
Someone (me) had wrapped the whole transition layer in one boundary:
tsx
// Before: one boundary around every cover variant
<Suspense fallback={null}>
<TransitionLayer>
<BootCover /> {/* subscribes to the store, reacts to edges */}
<ShutterCover />
<LabelCover /> {/* renders drei <Text>, suspends on font load */}
</TransitionLayer>
</Suspense>
The React Suspense reference says it plainly: "the whole tree inside Suspense is treated as a single unit... even if only one of these components suspends... all of them together will be replaced by the loading indicator." On first mount, nothing under the boundary commits until everything under it is ready. No commit means no effects, and no effects means no store.subscribe() call.
Meanwhile, the GPU prewarm gate sat outside the boundary. It finished, and moved the store warming → leaving. The boot cover reacts to that status change. Its listener compares the new state with the previous one:
tsx
// An edge-reacting subscriber: it acts on the transition, not the value
useEffect(() => {
return sceneStore.subscribe((state, prev) => {
if (state.status === 'leaving' && prev.status !== 'leaving') {
playExit() // when the timeline completes, it calls finishLeave()
}
})
}, [])
Zustand's vanilla store calls every listener synchronously with (state, previousState) on each setState. That is a clean way to detect an edge, but a listener only sees edges that happen after it subscribes. When the font finished parsing and the boundary finally committed, the boot cover subscribed into a store that was already at leaving. The edge was in the past. Nothing would ever call finishLeave(), so the watchdog did it 4 seconds later.
The detail that cost me time: the trigger was the font becoming ready after leaving, not the font request finishing late. Troika still has to parse the font after the bytes arrive, and under CPU throttle that parse took longer than the GPU prewarm. When I compared the two timestamps on each run, the correlation was 6 out of 6: font ready after leaving meant a stall, and font ready before leaving meant a clean transition.
Fix 1: wrap only the suspending leaf
The boundary existed for a good reason. A suspension that reaches the R3F root re-suspends the whole canvas, and in our dev setup under StrictMode that also lost the GL context. So the boundary had to stay. It only had to move down to the component that actually suspends:
tsx
// After: the variants mount immediately, only the label waits for its font
<TransitionLayer>
<BootCover />
<ShutterCover />
<LabelCover />
</TransitionLayer>
function LabelCover() {
return (
<group>
<CoverSlices />
<Suspense fallback={null}>
<Text font={labelFont} characters="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789">
{label}
</Text>
</Suspense>
</group>
)
}
Now every cover variant commits on the first render, every subscribe() runs before the prewarm gate can fire, and only the text label pops in when troika is ready. The characters prop is the drei-documented way to avoid a flash of unstyled glyphs. It limits what troika has to prepare, but it does not stop the suspension, so it is not a fix on its own.
After the fix, on the same production setup (4x CPU, 16 runs, 8 deep links), 0 of 16 runs stalled. The leaving → entering gap was 3 to 34 ms, the scene was visible at 1.2 to 3.1 seconds, and the cover completed through its own timeline instead of the watchdog.
If this is the kind of problem sitting in your launch backlog (a WebGL scene that works, but whose boot or transitions fail in ways nobody can reproduce), that is the work I take on. See how I work with studios and founders.
Fix 2: read current state once after subscribe()
Moving the boundary fixes this tree. It does not fix the pattern. Any edge-reacting subscriber that can mount late (lazy chunk, conditional render, a boundary someone adds next year) has the same hole. The defensive version subscribes first, then checks current state once:
tsx
useEffect(() => {
const unsubscribe = sceneStore.subscribe((state, prev) => {
if (state.status === 'leaving' && prev.status !== 'leaving') playExit()
})
// Catch up on an edge that happened before this component mounted
if (sceneStore.getState().status === 'leaving') playExit()
return unsubscribe
}, [])
Two rules make this correct:
- Subscribe before you read. Zustand's
setStatenotifies listeners synchronously, so if you subscribe and then callgetState()in the same synchronous block, no update can fall between them. Read first and subscribe second, and you open a window. - Make the action idempotent.
playExit()can now be reached from two paths. Guard it (astartedref, or a check on the timeline's state) so it runs at most once per transition.
If you use the subscribeWithSelector middleware, its subscribe(selector, listener, { fireImmediately: true }) option gives you the same catch-up call. You still need the action to be idempotent.
| Approach | Fixes this tree | Survives a future boundary or lazy mount | Cost |
|---|---|---|---|
| Boundary around the whole layer | No | No | Hides every sibling until the slowest leaf is ready |
| Boundary around the suspending leaf | Yes | No | One more <Suspense> per suspending leaf |
| Subscribe, then read current state once | Yes | Yes | An idempotency guard on the action |
| Both | Yes | Yes | Recommended for transition and boot code |
The leaf boundary alone fixed the measured stall. I recommend adding the catch-up read as well: the leaf boundary keeps the covers responsive, and the catch-up read means the next person who wraps something in <Suspense> cannot bring the stall back.
How I proved it on production without touching code
Local dev and a local production build did not reproduce it. Two things changed the order of events locally:
- The image CDN refused cross-origin requests from
localhost, so images failed fast andleavingalways fired after the font. To reproduce, I routed the image requests in Playwright, re-sent them with an allowedOrigin, and added the missing CORS header to the response. - Delaying the font with
page.routedid nothing, because the service worker served it from cache. Creating the context withserviceWorkers: 'block'fixed that.
To see the store itself on the live site, I read it through React's fiber tree from an init script. This relies on React internals, so treat it as a debugging tool only:
ts
await context.addInitScript(() => {
const findStore = () => {
const root = document.querySelector('main')
if (!root) return null
const key = Object.keys(root).find((k) => k.startsWith('__reactFiber$'))
let fiber = key ? (root as any)[key] : null
while (fiber) {
const value = fiber.memoizedProps?.value
if (value?.getState?.().transition) return value
fiber = fiber.return
}
return null
}
const timer = setInterval(() => {
const store = findStore()
if (!store) return
clearInterval(timer)
store.subscribe((s: any) => console.log(performance.now(), s.transition.status))
}, 50)
})
That logged every status with a timestamp. The 4,000 ms gap appeared in the log before I opened a single source file, and the font-ready timestamp landed on the wrong side of leaving in every stalled run.
The general lesson
- A gap exactly equal to a timeout constant means the driver was absent, not slow. Search for the watchdog that owns that number, then ask who was supposed to beat it.
- Never put a Suspense boundary around components that subscribe to an imperative store and act on edges. Suspense delays the commit, and the commit is when the subscription starts.
- Edge-reacting code needs a catch-up path. Subscribe, read current state once, and make the reaction idempotent.
This is the same class of bug as the one in why a WebGL hero disappears on browser back and a Next.js page transition that breaks on a redirect: a lifecycle path that ran once in testing and in a different order in production.
FAQ
Does Suspense unmount components that already rendered?
On first mount, the components under a boundary never mount while any of them is suspended, and React discards that render's state. If content that is already visible suspends again, React hides it and cleans up its layout effects. React re-runs them when the content shows again. Either way, a subscription set up in an effect is not active while the boundary shows its fallback on first mount.
Why does drei Text suspend the whole scene?
drei's <Text> suspends while troika loads and prepares the font. Suspension climbs to the nearest <Suspense> boundary. If that boundary wraps your whole scene or transition layer, everything under it waits for the font. Put a boundary directly around the <Text>.
Is useSyncExternalStore safe from this?
A component that renders from useSyncExternalStore (or a zustand hook) reads the current value when it renders, so it shows the right state when it mounts late. It still cannot see a transition that already happened. If your logic needs "the status just changed to X", you need the catch-up read.
Why did the bug not reproduce locally?
The stall needs a specific order: the font becomes ready after the store reaches leaving. Network, CORS failures, service worker caching and CPU speed all move those two events. Reproduce on production with CPU throttling, and block the service worker when you need to control asset timing.
I'm Hon Tran, an Awwwards Jury member and creative developer with 19 international awards. I build WebGL and motion-heavy sites, and I debug the ones that already exist. If your scene, transitions or boot sequence fail in ways your team can't pin down, let's talk about your project, or browse recent work first.
04 — Engineering note
For agencies, studios and brands
Need this levelof execution?
05 — Related notes
Same tags · same craft
Continue the thread.
- 01Why Your WebGL Hero Disappears on Browser BackEngineering note / 068 · 11 Jul 26Your Next.js WebGL background is fine on first load and Link nav, then blank after the browser Back button? Here's the popstate root cause and the R3F rebuild fix.10 min
- 02React Three Fiber Tutorial for BeginnersEngineering note / 022 · 27 Jun 26A hands-on React Three Fiber tutorial for beginners — set up the Canvas, build a mesh, animate with useFrame, add lights and OrbitControls, and load a 3D model.8 min
- 03Three.js Performance Optimization: A Practical GuideEngineering note / 024 · 27 Jun 26Three.js performance optimization that actually moves the FPS: cut draw calls, batch geometry, dispose memory, and render on demand in React Three Fiber.8 min