# Sentry vs hydration-proof

> A Sentry hydration error issue shows what broke for real users after deploy. hydration-proof finds mismatches before deploy. How the two fit together.

Source: https://hydration.jscrate.dev/docs/compare/sentry-hydration-errors
Last updated: 2026-09-18

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](https://docs.sentry.io/product/issues/issue-details/replay-issues/hydration-error/)).
- **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](https://sentry.io/changelog/2024-1-5-diff-hydration-errors-with-replay)).

## 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](https://hydration.jscrate.dev/docs/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](https://hydration.jscrate.dev/docs/scenarios).
- **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](https://hydration.jscrate.dev/docs/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?".

1. Run hydration-proof in CI, so known mismatches never ship:

   ```bash
   npx hydration-proof test --mode both
   ```

2. Keep Sentry in production for what tests cannot reproduce: a new browser extension, a CDN setting someone changed, data you never tested with.
3. When Sentry reports a hydration error on a route, add a [scenario](https://hydration.jscrate.dev/docs/scenarios) 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](https://docs.sentry.io/product/issues/issue-details/replay-issues/hydration-error/), how hydration errors are detected, the diff tools and their limitations
- [Sentry changelog: Diff Hydration Errors with Replay](https://sentry.io/changelog/2024-1-5-diff-hydration-errors-with-replay), January 5, 2024, SDK 7.90.0 requirement
- [hydration-proof: how it works](https://hydration.jscrate.dev/docs/how-it-works)

## Related

- [Hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)
- [Scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios)
- [All comparisons](https://hydration.jscrate.dev/docs/comparison)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)