xenophobic-harlequin

How to debug streaming hydration errors

I have a hydration error that occurs every ~5 loads on both dev and prod. I'm trying to use something like next-themes to set a theme class on the root element which is where this error originates, but I'm not quite sure where to start with it

Uncaught Error: This Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering. The usual way to fix this is to wrap the original update in startTransition.
    at updateDehydratedSuspenseComponent (chunk-PFMSSJLQ.js?v=2f7b2551:15345:56)
    at updateSuspenseComponent (chunk-PFMSSJLQ.js?v=2f7b2551:15118:24)
    at beginWork (chunk-PFMSSJLQ.js?v=2f7b2551:15939:22)

Uncaught Error: This Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering. The usual way to fix this is to wrap the original update in startTransition.
    at updateDehydratedSuspenseComponent (chunk-PFMSSJLQ.js?v=2f7b2551:15345:56)
    at updateSuspenseComponent (chunk-PFMSSJLQ.js?v=2f7b2551:15118:24)
    at beginWork (chunk-PFMSSJLQ.js?v=2f7b2551:15939:22)

19 Replies

like-gold•10mo ago

I'm also using Next-Themes in a UI lib and I get this same exact error in the currently latest release. Will try to narrow this down. Edit: I confirmed when I removed Next-Themes. That it is the issue. As I get no errors on startup. Now to try and resolve... Resolved. I will open up an issue in next-themes repo.

like-gold•10mo ago

https://github.com/pacocoursey/next-themes/issues/326

GitHub

[Bug]: [Tanstack Start] Uncaught Error: This Suspense boundary rece...

What happened? Hello. I'm using tanstack start and I'm encountering the issue: Uncaught Error: This Suspense boundary received an update before it finished hydrating. This caused the bounda...

robust-apricot•10mo ago

I did some looking into this in general in https://discord.com/channels/719702312431386674/1306439858503417936/1306439858503417936, https://github.com/TanStack/router/discussions/2764, https://bsky.app/profile/ballingt.com/post/3lb4ce4rjyk22 In my case this was a React Context update causing the issue. My takeaway from the discussions was that we probably do want to avoid these immediately after render context updates. What's the effect of the startTransition here @Paul, I'm not clear on when startTransition is allowed / when it helps.

GitHub

Dealing with components streaming in later, updates before hydratio...

I'm still getting adjusted to the new world where suspense boundaries cause React subtrees to stream in and hydrate later. In this world there's no definitive "hydration of the entire ...

Tom Ballinger (@ballingt.com)

Bluesky Social

Tom Ballinger (@ballingt.com)

re "Suspense boundary received an update before it finished hydrating," how do you think about this new streaming world @phry.dev? I opened https://github.com/TanStack/router/discussions/2764 about the error, now thinking about avoiding updating React Contexts in Convex stuff for this reason

like-gold•10mo ago

What's the effect of the startTransition here

I don't know. All I did was replace the code (see issue) with StartTransition and the problem went away. What the longterm out come is. I have no idea. Sorry I cannot be more help.

robust-apricot•10mo ago

no problem, just a heads up. I'm confused about when the startTransition solution makes sense and whether every library like thesems should be using it. I'll follow that issue. also interested in whether suppressHydrationWarning is an appropriate solution, I see lots of people using it with that next-themes

like-gold•10mo ago

I see that in the NextJS discord. A lot of people use it willy-nilly lol. So I don't know.
Unfortunately, I think I'm going to have to drop Start. As I've taken it as far as I can and it doesn't completely satisfy my use case.

xenial-black•10mo ago

I’m also using it with my own theme solution https://github.com/nekochan0122/tanstack-boilerplate/blob/main/src/routes/__root.tsx#L142 since you can’t the correct theme value on server side, so the hydration warning is expected even if you save the theme value in session storage or database, you still can’t get the correct prefer theme if your website use “systems” theme by default

xenial-black•10mo ago

robust-apricot•10mo ago

Sorry to hear, hope you get to give it another shot in a few months once all this is ironed out. Curious to hear about the use case, you'll get no argument from me to use something that doesn't work for you. Ooo cool, what's ScriptOnce?

like-gold•10mo ago

It's an electron app. That's the gist of it.

xenial-black•10mo ago

https://discord.com/channels/719702312431386674/1302275380471922861/1303157794811150449

xenial-black•10mo ago

export from tanstack router

robust-apricot•10mo ago

would love to hear what you end up using, I have no idea what the best approach there is

xenial-black•10mo ago

source code https://github.com/nekochan0122/tanstack-boilerplate/blob/main/src/components/theme.tsx

other-emerald•10mo ago

https://discord.com/channels/719702312431386674/1238170697650405547/1309809301845577729 FYI I'm running into the same issues while using NextUI, thanks for getting the heads start on this conversation

like-gold•10mo ago

I went back to using Tanstack Router. The issue doesn't exist here. Only with Start.

rising-crimson•10mo ago

The basic start example has hydration errors too

fascinating-indigo•10mo ago

please create a GitHub example for this

rising-crimson•10mo ago

Here's one of the example stackblitzs. Getting the same errors locally https://stackblitz.com/github/tanstack/router/tree/main/examples/react/start-basic?embed=1&theme=dark&preset=node&file=src/main.tsx

.localservice@runtime.d3acb9e1.js:26 Warning: Extra attributes from the server: br-mode,saccades-color,fixation-strength,saccades-interval,style
    at body

.localservice@runtime.d3acb9e1.js:26 Warning: Extra attributes from the server: br-mode,saccades-color,fixation-strength,saccades-interval,style
    at body

StackBlitz

Router Start Basic Example - StackBlitz

Run official live example code for Router Start Basic, created by Tanstack on StackBlitz

Gaming

Programming

How to debug streaming hydration errors

Did you find this page helpful?