Hydration Proof

Search documentation

Find a page or section

HP9001: Hydration did not finish in time

hydration-proofv1.0.0View as Markdown

HP9001 (hydration-timeout) means React loaded but hydration did not finish before the timeout. Raise the timeout or find the Suspense boundary that hangs.

HP9001 (hydration-timeout) means React loaded on the page, but hydration did not complete before the timeout, so the page could not be compared. Usually a Suspense boundary never resolves in the test environment, or the page is very slow to hydrate. Find the boundary that hangs, or increase the hydration timeout.

CodeHP9001
Namehydration-timeout
Default severityError
GroupTest run problems
What it meansReact was on the page but hydration did not complete before the timeout.

What the HP9001 hydration timeout finding means

hydration-proof waits for React's hydration to finish before it takes its snapshots. Once React is on the page, it waits up to ready.hydrationTimeout (15 seconds by default), within the page's overall ready.timeout (30 seconds). When the time runs out, the finding says how many boundaries are still waiting:

Hydration did not finish: 2 Suspense or Activity boundaries are still dehydrated.
Hydration did not finish before the timeout.

It is an error: nothing after hydration could be checked on that page.

The info variant

React hydrates some boundaries only when the user interacts with them. When every pending boundary already has its content and the page has been quiet for two seconds, hydration-proof stops waiting and reports HP9001 as info instead:

React did not hydrate 1 Suspense boundary whose content had already arrived; React hydrates it on the first interaction.

The page is still tested; only those boundaries are not compared.

Likely causes

  • A Suspense boundary whose data never arrives in the test environment: an API that is not running, a request the test browser cannot reach, a promise that never resolves.
  • A slow scenario: throttled network (network: "slow-3g") or CPU (cpu: 4) with a large bundle.
  • A script error that stops hydration part-way; look for HP2007 on the same page.

How to fix it

Increase the hydration timeout, or check for Suspense boundaries that never resolve in the test environment.

  1. Open the route with --headed and watch which part stays in its fallback.
  2. Make the data available to the test: start the API, seed it in hooks.setup, or answer the browser's requests with mocks in the scenario (see scenarios).
  3. If the page is just slow, raise the limits. Keep ready.timeout above ready.hydrationTimeout, since it covers the whole page:
hydration-proof.config.ts
import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  ready: { hydrationTimeout: 30_000, timeout: 60_000 },
});

A route object can set its own ready options, so one slow page does not slow down the rest; see routes.