Hydration Proof

Search documentation

Find a page or section

HP5005: Client-side navigation failed

hydration-proofv1.0.0View as Markdown

HP5005 (navigation-error) means navigating to a route inside the app threw an error, its RSC or data request failed, or the URL never changed. How to fix it.

HP5005 (navigation-error) means navigating to the route inside the app failed: the navigation threw an error, its data request (an RSC request in Next.js) failed, or the URL never changed. The route works when loaded directly and breaks when users click a link to it. Open it through a link and check the console and network tab.

CodeHP5005
Namenavigation-error
Default severityError
GroupInteraction during hydration
What it meansNavigating to the route inside the app threw an error, its data request failed, or the URL never changed.

What the HP5005 navigation error finding means

The finding comes from the navigation checks (checks.navigation: true or --navigation). hydration-proof opens another page, navigates to the route with the app's router and records what happens after the navigation starts:

  • an uncaught error on the page;
  • an RSC request for the route that fails or answers with a status of 400 or more;
  • a URL that never changes to the route.

The first problem is in the message, and every problem is listed as evidence:

Navigating to this route from another page failed: The RSC request /dashboard?_rsc=1m2k3 answered 500.

RSC requests and prefetches also appear in the report's timeline. It is an error. A navigation that the framework turns into a full page load (for example to another root layout) is noted in the timeline, not reported.

Likely causes

  • A Server Component of the route that throws for RSC requests, for example because it reads a header or cookie that only a full page request has.
  • Middleware or a proxy that blocks or redirects RSC requests.
  • A loader or data request that fails when called from the client.
  • A client component that throws while rendering the new route.

How to fix it

  1. Open the route through a link in the browser and check the console and the network tab for the failed request.
  2. Make sure Server Components of the route do not throw for requests that come from client-side navigation (RSC requests).
  3. Run only this route to reproduce it quickly, with the browser visible (below).
  4. To navigate from a specific page, set navigateFrom on the route, or checks.navigation.from for all of them; see routes.
npx hydration-proof test --navigation --route /dashboard --headed

When it is expected

A route that is only reachable by a full page load can be ignored with an ignore.issues rule for code: "HP5005" and its route; see ignoring findings.