Issue codes

Every finding carries one of the hydration-proof issue codes: HP1001 for text that differs between server and client, HP3001 for invalid HTML nesting, and so on. A code never changes meaning, so you can use it in ignore rules, baselines and budgets. Each code below links to a page with its causes and fixes.

How to read a code

The first digit is the group. Each code also has a kebab-case name (text-mismatch) that is as stable as the code itself.

The code shows up everywhere a finding does: the terminal, report.json, the HTML report, the SARIF rule id, the JUnit failure type and the GitLab check_name. See report formats for each one.

Severity and --fail-on

Every code has a default severity. It decides whether the run fails:

--fail-on never (or ci.failOn: 'never') never fails the run, and ci.maxWarnings fails it when there are more warnings than you allow. A finding's severity is usually its code's default; a few are raised or lowered. For example, a difference hidden by suppressHydrationWarning that does not look intentional is a warning instead of info. Budgets per severity, route or code are covered in baselines and budgets.

Ignore a code

Ignored findings stay in the report, marked as ignored, and do not fail the run. A rule needs a reason, and an expiry date keeps a temporary exception from becoming permanent: once it passes, the finding fails the run again.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  ignore: {
    issues: [
      {
        code: "HP1004",
        route: "/legacy/**",
        reason: "Old theme system",
        expires: "2026-12-31",
      },
    ],
  },
});

A rule can match a code, a route glob, a selector or a fingerprint. Ignoring findings covers selectors, attributes and text patterns as well.

Fingerprints

Every finding also has a fingerprint. It stays the same across runs as long as the problem is the same: same code, route pattern, element and attribute. Ignore rules and baselines match on it, and the SARIF report passes it to code scanning, so an alert is recognized from one run to the next.

DOM mismatches

The server HTML and the first client render differ: text, attributes, inline styles, class names, elements, whitespace, form state or the document head. It also covers the branches React threw away and rendered again on the client.

Problems React reported

Errors and warnings React logged itself. When a DOM finding explains them, React's message is attached to that finding as evidence instead; these codes are for the reports nothing else explains, and for page errors.

Markup the browser repaired

Nesting the HTML parser rewrites before React hydrates, nested interactive elements, duplicate ids and useId collisions between React roots.

Changes made outside React

Scripts, browser extensions, CDNs and proxies that changed the page before React hydrated it.

Interaction during hydration

What a user does before the page is interactive, and client-side navigation compared with a direct load. Most of these need checks.interactions or checks.navigation.

suppressHydrationWarning audit

Differences that suppressHydrationWarning hides, structural differences it cannot hide, and suppressions with nothing to suppress.

Test run problems

The page did not load, React never hydrated, or the page never settled.

Related

• Common causes of hydration errors, with a fix for each
• React hydration error messages, decoded
• Ignoring findings on purpose
• How hydration-proof works: which comparison finds what
• Detect hydration errors in CI