useHydrateAtoms causes hydration mismatch, unlike React context

[schardev]

Bug Description

I’ve got an app where I read a currency cookie on the server, pass it down via a Jotai Provider, and then use useHydrateAtoms on the client to initialize currencyAtom with that value.

This setup works fine on the first render, but if I change the cookie and refresh the page, I get a hydration mismatch error.

Interestingly, if I turn on dangerouslyForceHydrate, the issue goes away — but I’m a bit hesitant to use it since the docs mention it "may behave wrongly in concurrent rendering".

What’s more confusing is that I tried this exact flow with React context instead of Jotai, and everything worked perfectly — no hydration issues at all. So I’m wondering:
Why does useHydrateAtoms behave differently than React context in SSR?

Steps to reproduce:

1. Build the app (pnpm build) or just run the dev server — same behavior either way
2. Click the first link to set the currency cookie
3. Go back to the homepage and visit the "Without dangerously" link
4. Do a hard refresh — the value should be correct at this point
5. Open dev tools, change the currency cookie to something else
6. Hard refresh again — now the jotaiCurrency value flickers (starts with the old value, then switches to the server one), causing a hydration error. Meanwhile, the React context value stays correct throughout

Repeat the same steps on the "With dangerously" link and you’ll see both context and Jotai behave the same.

Here's a screen recording of both flows:

Without dangerously

without-dangerously-flag.mp4

With dangerously

with-dangerously-flag.mp4

So yeah — just trying to understand the difference here. I assumed Jotai and context would behave similarly in SSR scenarios. And also, if dangerouslyForceHydrate fixes the problem, is it really that dangerous? Why is it labeled that way?

Maybe I’m missing something — if you have any docs or resources that explain what’s going on under the hood, that'd be great.

Thanks.

Reproduction Link

https://github.com/schardev/jotai-context-issue

[dai-shi]

This looks wrong. useHydrateAtoms should be used under the <Provider> tree.
And you shouldn't pass store={store} prop, otherwise it can be shared across sessions.

export const JotaiProvider = ({
  children,
  initialValue,
  dangerouslyForceHydrate,
}: {
  children: React.ReactNode;
  initialValue: string;
  dangerouslyForceHydrate?: boolean;
}) => {
  useHydrateAtoms([[currencyAtom, initialValue]], {
    store,
    dangerouslyForceHydrate,
  });
  return <Provider store={store}>{children}</Provider>;

[schardev]

useHydrateAtoms should be used under the tree

Can still reproduce even if under Provider with store={store}

you shouldn't pass store={store} prop, otherwise it can be shared across sessions

Correct me if I'm wrong, but since the provider file uses "use client", doesn’t that mean it runs on the client side for every request and creates a new store each time?

Well, yes, removing store={store} seems to fix the issue, but this is just a contrived example. In our prod app, we use the store outside of React to track atoms. I know we could move that logic inside the provider tree, but we have a lot of atoms, so refactoring everything would be a pain. Is there any way to still use the store prop and have proper hydration? Is dangerouslyForceHydrate the only workaround?

[dai-shi]

removing store prop is important if you render it on the server. It's more important than hydration mismatch error. If you have store outside React tree, you have a risk of leaking information.

[schardev]

So it seems the only way forward is this:

const [store] = useState(() => createStore());

return (
  <Provider store={store}>
    <Hydrate initialValue={initialValue}>
      {children}
    </Hydrate>
  </Provider>
);

Hydrate will just pass the initialValue to useHydrateAtoms.

[schardev]

If you have store outside React tree, you have a risk of leaking information

This is actually really important but I found no mentions of it in the store docs. Should we update the docs?

EDIT:

And in the provider docs we're showing the usage of creating a store outside of React without a warning or a link to relevant page describing the risk involved.

[dai-shi]

Maybe it's written in some other docs. Feel free to open a PR.

const [store] = useState(() => createStore());

It looks good. Essentially, what is does is the same as <Provider>.
So you should be able to do const store = useStore() under the tree. I think it's more preferable, but either is fine if you know what you are doing.