Angular’s NG0500: Hydration Node Mismatch means the DOM in the browser does not match the structure Angular expects from server-side rendering. Find where the trees diverge—often direct DOM changes, invalid HTML, different server and browser render paths, or modified HTML delivery—and correct that cause. Use ngSkipHydration only as a temporary workaround: it skips hydration for a component subtree and makes Angular render that subtree again.
What NG0500 means
With server-side rendering (SSR), Angular sends HTML to the browser. During hydration, Angular reuses that existing DOM and matches it to the client application’s expected structure. NG0500 appears when Angular encounters a different node than it expects at a position in that structure. The error’s console details can point to the location where the mismatch was detected.
As an Amazon Associate I earn from qualifying purchases.
For example, a template may expect a <div> as its first child, but code inserts a <p> before it. The browser now has a different first child, so Angular cannot match the DOM as expected.
Recommended Free Tools
Common causes and how to fix them
Code or a library changes the DOM directly
Browser APIs such as appendChild, insertBefore, node removal or movement, and assignments to innerHTML or outerHTML can add, remove, replace, or rearrange nodes outside Angular’s rendering model. Third-party libraries that mutate the DOM can cause the same divergence.
#1 Best Overall
Prefer Angular templates and its declarative rendering APIs so Angular owns the structure. If a DOM-dependent script or library must run, defer its DOM changes until after hydration where possible; Angular documents AfterNextRender for work intended to happen after rendering.
Renderer2 is not a blanket fix for structural DOM manipulation: Angular’s DOM API guidance says its APIs do not support DOM manipulation during SSR or build-time prerendering.
Invalid HTML is repaired by the browser
The browser may normalize invalid markup into a tree that differs from the one Angular expects. Check for structures such as a <div> inside a <p>, an <a> nested inside another <a>, or a table missing an explicit <tbody>. Use valid nesting and include <tbody> where needed.
Server and browser render different initial content
The server and browser need to produce the same initial DOM structure. A conditional that selects different branches based on whether the code is running in the browser can leave Angular with different content to hydrate. Keep initial rendering consistent, including the data and conditions that determine which elements appear.
Rank #3
Delivered HTML was altered after SSR
Hydration depends on the server-rendered HTML reaching the browser intact. Angular’s hydration guide states: “The HTML produced by the server side rendering operation must not be altered between the server and the client.” A CDN optimization or custom HTML transformation that strips Angular comment nodes or whitespace can change the structure Angular needs. This can explain a mismatch that happens only in production.
Compare the HTML actually delivered to the browser with the server-rendered output. Preserve Angular-generated comments and whitespace, and disable any CDN or post-processing feature that removes them. Angular discusses altered SSR content separately in NG0507.
Debug NG0500 step by step
- Read the browser console error. Note the reported DOM location and inspect that component’s subtree first. Angular’s NG0500 reference includes details about the error and an example of a direct DOM mutation.
- Search the component and its dependencies for DOM changes. Look for
document,querySelector,appendChild,insertBefore, node removal or movement,innerHTML,outerHTML, and calls to libraries that modify markup. - Validate the HTML structure. Correct invalid nesting and add explicit table sections such as
<tbody>. - Compare initial rendering paths. Check whether server and browser conditions or data produce different elements before hydration completes.
- For production-only failures, inspect the final response. Confirm that the HTML received by the browser still contains the comments and whitespace Angular rendered; investigate CDN rules and custom response transformations.
- Inspect hydration in Angular DevTools. The Angular hydration guide describes using DevTools to inspect hydration status and highlight a component associated with a mismatch.
When to use ngSkipHydration
ngSkipHydration is a last-resort workaround for a component that cannot yet be made hydration-compatible. It must be placed on a component host node, not an arbitrary child element. Angular skips that component and its descendants, destroys that subtree, and renders it again on the client. That subtree therefore does not retain hydration’s DOM-reuse benefits.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Putting the attribute on the root application component effectively skips hydration for the whole app. Prefer fixing the underlying DOM mutation, markup, rendering mismatch, or HTML transformation, then remove the workaround when the component is compatible. See Angular’s hydration guide and NG0500 documentation for the supported placement and behavior.
NG0500 versus nearby hydration errors
Related error codes describe distinct problems; check the exact code rather than treating all hydration failures as interchangeable.
| Error | What it reports | Reference |
|---|---|---|
| NG0500 | Angular encountered a DOM node that does not match the structure it expected during hydration. | Angular NG0500 |
| NG0502 | Angular expected a node at a position, but no node was present. | Angular NG0502 |
| NG0507 | SSR HTML was altered after rendering; removing comments or whitespace is among the documented examples. | Angular NG0507 |
Angular’s Error Encyclopedia lists these and other error codes.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
