Modern Angular

Guide · 8 min · Jun 6, 2026

NG0500 Hydration Node Mismatch: the Real Fix Is Not ngSkipHydration

NG0500: Hydration Node Mismatch means the DOM Angular built on the client did not match the HTML your server sent. The popular fix, ngSkipHydration, silences it by throwing hydration away for that subtree, which the docs call a last resort and the breaking component a bug. NG0500 is a diagnosis: something altered the DOM between server and client, and it is usually one of a short list.

The error, and the family

The message opens with NG0500: During hydration Angular expected .... The official description is precise: during hydration Angular expected the DOM structure it rendered and annotated on the server, but on the client the DOM tree was different. Hydration reuses the server-rendered DOM instead of re-creating it, so any divergence between the two trees stops it cold.

NG0500 is the headline of a family, and you may have pasted a neighbor. NG0501 is missing siblings, NG0502 a missing node, NG0503 unsupported projection of DOM nodes, NG0504 a skip-hydration flag on an invalid node, NG0505 no hydration info in the server response, NG0506 an application that stays unstable, and NG0507 HTML that was altered after server-side rendering. They all trace back to the same idea: the client DOM is not what the server promised.

What actually causes it

The causes are a short list, and most are not subtle once you know them. The sneaky one is invalid HTML. The browser silently fixes malformed markup, so the server sends one tree and the browser parses another, and hydration sees a mismatch you never wrote on purpose.

The others: code that touches the DOM directly (native APIs, innerHTML, outerHTML, appendChild, moving nodes), third-party libraries that render into the DOM (the docs name D3 charts), and preserveWhitespaces set differently between the server and client builds.

Cause	Why hydration breaks	Direction of the fix
Invalid HTML nesting	The browser normalizes it; client tree differs from server	Fix the markup so both parse identically
Direct DOM manipulation	innerHTML, appendChild, node moves change the tree	Use Angular bindings or Renderer2
Third-party DOM library (D3, etc.)	It mutates the DOM during and after SSR	Run it client-only, after hydration
Inconsistent preserveWhitespaces	Server and client builds emit different whitespace	Align the setting across both builds

The invalid-nesting trap (the browser rewrites it)html

<!-- Breaks hydration: the browser hoists the <div> out of the <p>,
     so the client tree no longer matches the server HTML -->
<p>{{ summary }} <div class="badge">{{ status }}</div></p>

<!-- Valid: server and client parse the same tree -->
<p>{{ summary }} <span class="badge">{{ status }}</span></p>

ngSkipHydration is a tourniquet, not a cure

Search NG0500 and the top answer is ngSkipHydration. It works, and that is the problem. The attribute forces Angular to skip hydrating the whole component and its children, so the error goes away because hydration goes away for that subtree. Put it on the root and you have disabled hydration for the entire app while keeping the SSR cost.

The docs are blunt about its role: it is a last resort, and a component that breaks hydration should be treated as a bug to fix. So if you reach for it, scope it to the narrowest host, and treat it the way the SSR and hydration playbook treats it: every ngSkipHydration gets an owner, a reason, and a removal plan, or it becomes permanent scar tissue nobody dares touch.

The real fixes, by cause

Invalid nesting: correct the markup so the server HTML and the browser-parsed DOM are the same tree. A <div> inside a <p>, an <a> inside an <a>, a <table> without a <tbody>, those are the usual offenders.

Direct DOM work: move it onto Angular's APIs, bindings, Renderer2, the template, so the framework owns the structure on both sides. When you genuinely need a DOM library that paints after the page exists, run it client-only with afterNextRender, which fires after hydration and never on the server, so there is nothing for hydration to mismatch.

Client-only DOM work, after hydrationts

// Breaks hydration: the chart lib mutates the DOM on the server and
// the client, and the two trees do not match
ngOnInit() { this.renderChart(this.host.nativeElement); }

// Fixed: run it only on the client, after hydration completes
private readonly host = inject(ElementRef);
constructor() {
  afterNextRender(() => this.renderChart(this.host.nativeElement));
}

When it only breaks in production

Some NG0500 reports pass locally and fail only once deployed. The rule the docs state is that the HTML produced by SSR must not be altered between the server and the client. Anything in the middle that rewrites the response breaks that: a proxy or CDN that minifies HTML, an edge worker that injects a tag, a security layer that reorders attributes. The server rendered one tree, the browser received another, and NG0507 is the explicit code for HTML altered after rendering.

So when the component is clean but the error is real, look at the pipe between your server and the browser before you reach for ngSkipHydration. The fix is to stop the rewrite, not to skip hydration for a component that was never the problem.

Reusable artifact

Debugging NG0500 hydration mismatch

Read which node the message names; that is where the server and client trees diverged.
Check the template for invalid HTML nesting (div in p, a in a, table without tbody); the browser rewrites it.
Find direct DOM work (innerHTML, appendChild, native APIs) and move it onto Angular bindings or Renderer2.
For a third-party DOM library, run it client-only with afterNextRender so it never runs during SSR.
If it only fails in production, check for a proxy or CDN altering the HTML in transit (NG0507).
Use ngSkipHydration only as a last resort, scoped to the narrowest host, with an owner and a removal plan.

FAQ

What does NG0500 Hydration Node Mismatch mean?

During hydration, Angular reuses the DOM your server rendered. NG0500 means the DOM tree on the client was different from the one the server produced, so Angular cannot match them up. Something changed the structure between server and client.

Should I just add ngSkipHydration?

Only as a last resort. The docs say it forces Angular to skip hydrating the component and its children, so you keep the SSR cost but lose hydration for that subtree, and they call a hydration-breaking component a bug to fix. If you use it, scope it narrowly and give it a removal plan.

Why does NG0500 happen with valid-looking templates?

Invalid HTML nesting is the common surprise: a <div> inside a <p>, an <a> inside an <a>, or a <table> without <tbody>. The browser silently rewrites the markup, so the parsed DOM no longer matches the server HTML.

It works locally but NG0500 fires in production. Why?

The SSR HTML must not be altered between server and client. A proxy or CDN that minifies HTML, or an edge layer that injects or reorders markup, changes the tree the browser receives. NG0507 is the explicit code for HTML altered after rendering.

Sources checked

Modern Angular Playbook

This article is one play.

The Modern Angular Playbook collects the diagnostic, the adoption matrix, eleven plays, and the 30-day plan. Free, in English and Portuguese.

You get both PDFs by email, through the Dojo IA list.

Open playbook →

André Ramosavailable for remote roles, UTC−3Get in touch →

The error, and the family#

What actually causes it#

ngSkipHydration is a tourniquet, not a cure#

The real fixes, by cause#

When it only breaks in production#