A Sentry hydration error issue tells you that hydration failed for real users in production, and with Session Replay attached it shows a diff of the page before and after hydration. hydration-proof finds mismatches before you deploy, by testing every route in a browser in CI. One observes, the other prevents, and they work well together.
At a glance
| Sentry | hydration-proof | |
|---|---|---|
| When | After deploy, in your users' browsers | Before deploy: locally and in CI |
| What it sees | Errors React reports on the pages people visit | Every tested route, in the scenarios you configure |
| The diff | With Session Replay: HTML diff, tree compare and image comparisons | Server and client values of each differing element |
| Real-world conditions | Yes: real extensions, CDNs, data and devices | Simulated: locales, timezones, themes, viewports, storage |
| Mismatches React does not report | No error is raised to capture | Reported (attribute mismatches in React 19 production) |
| In your app | The Sentry SDK and, for the diff, Session Replay | Nothing |
| Cause | You infer it from the diff | A likely cause, which --probe can prove |
What the Sentry hydration error view does well
- Real users, real conditions. Sentry sees the extensions, CDN behavior, data and devices your users actually have, which no test environment fully reproduces.
- A diff from production. When a hydration error event has a replay, the issue page offers diff tools: an image slider, side-by-side images, a tree compare of added, removed and changed DOM nodes, and an HTML diff (Sentry docs).
- Two ways in. Hydration errors reach the issue stream as regular error events, or are detected inside a replay and turned into an issue.
- Privacy by default. Personal data on the page is masked or blocked before the replay is sent.
Sentry introduced the replay diff in January 2024; it needs Session Replay and a browser JavaScript SDK version 7.90.0 or later (changelog).
Where hydration-proof differs
- Before users see it. A hydration error in Sentry has already happened to someone. hydration-proof fails the pull request instead (CI).
- Every route, not only visited ones. Sentry sees the pages people open, and replays only for sessions that were recorded. hydration-proof tests every discovered route in each configured scenario.
- Mismatches React does not report. Sentry's hydration issues come from error events, or from errors detected in a replay. React 19 production builds do not report attribute mismatches at all, so no error is raised for a monitor to capture. hydration-proof compares every attribute with what React renders on the client.
- Development builds too. Sentry's docs note that "sometimes the diff Sentry shows doesn't contain any visible changes", a limitation of debugging React in production mode. hydration-proof can test the development build next to the production build (
--mode both) to get React's full messages and exact source lines. - A cause. Each finding comes with a likely cause and a fix, and probes prove the cause by changing one factor at a time.
- Nothing in your bundle. hydration-proof's runtime exists only in the test browser.
Use both
They answer different questions: "will this deploy hydrate?" and "did it hydrate for our users?".
-
Run hydration-proof in CI, so known mismatches never ship:
npx hydration-proof test --mode both -
Keep Sentry in production for what tests cannot reproduce: a new browser extension, a CDN setting someone changed, data you never tested with.
-
When Sentry reports a hydration error on a route, add a scenario that reproduces its conditions (the locale, the timezone, the stored state), so hydration-proof catches it from then on.
Sources
As of September 2026:
- Sentry: Hydration Error, how hydration errors are detected, the diff tools and their limitations
- Sentry changelog: Diff Hydration Errors with Replay, January 5, 2024, SDK 7.90.0 requirement
- hydration-proof: how it works