Free tools Windows power users keep installed
One-click scans. No signup required.
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Angular’s NG0502 error means hydration expected to find a DOM node at a particular location but it was missing. The server-rendered page and the browser DOM no longer match where Angular is trying to reuse the server markup. Compare those two DOM states, then check for code, scripts, or invalid HTML that changed the structure before hydration. Fixing that mismatch is preferable to disabling hydration.
What NG0502 means
Angular hydrates a server-rendered page by reusing its existing DOM. For that to work, the browser DOM must retain the structure Angular expects from the server output. With NG0502, Angular cannot find a node at the expected position. The error reference describes it as “Hydration Missing Node” and points to the related NG0500 debugging guidance; the code alone does not identify the missing node or its cause. See Angular’s NG0502 reference.
The mismatch can involve elements, text, or comment nodes—including nodes associated with whitespace. A browser or script may have changed the DOM after server rendering but before Angular began hydration.
How to find the mismatch
- Reproduce it on the affected route. Note the component and surrounding page state when the error appears. Use the browser console and rendered page as starting points; NG0502 itself does not name the responsible component or node.
- Compare the server response with the browser DOM at hydration time. Inspect the HTML returned by server-side rendering and the DOM in the browser. Look for nodes or comments that are missing, added, or moved between the two. Angular requires the server-rendered output not to be altered before hydration. See the Angular Hydration guide.
- Search the affected component and its dependencies for DOM changes. Check for
documentqueries,appendChild, node removal or movement, and assignments toinnerHTMLorouterHTML. Replace direct DOM manipulation with Angular-supported rendering approaches where possible. - Validate the template’s HTML structure. Check tables and nested elements against the examples below. The browser may normalize invalid markup, producing a DOM tree that differs from the one Angular expects.
- Check scripts that run before hydration. Analytics and other third-party scripts can alter the page. Where feasible, defer DOM-mutating scripts until after hydration; Angular’s guide describes using
AfterNextRenderfor work that should run after rendering. - Review whitespace settings. Angular recommends the default
preserveWhitespaces: false. If whitespace preservation is enabled, keep the setting consistent between server and browser builds. This can contribute to a mismatch, but does not explain every NG0502 error.
Common causes and repairs
Direct DOM manipulation
Native DOM operations can insert, remove, or move nodes outside Angular’s expected rendering structure. Refactor the behavior to use Angular APIs where possible, so server and browser rendering produce compatible DOM.
#1 Best Overall
Invalid or incomplete HTML
Use valid nesting and make implied structure explicit. Angular specifically calls out tables without a <tbody> and a <div> inside a <p> as structures to check; nested anchors are another invalid pattern. For example, write <table><tbody>...</tbody></table> rather than relying on the browser to insert a table body.
Third-party scripts
A script that changes the DOM before Angular hydrates can create the mismatch even if the Angular template itself is unchanged. Defer that work until after hydration when feasible, or change the integration so it does not rewrite server-rendered markup.
When to use ngSkipHydration
ngSkipHydration is a scoped workaround when an incompatible component cannot be refactored immediately. It must be placed on a component host; it is not an instruction to put the attribute on arbitrary elements. Angular skips hydration for that component and its children, destroying and re-rendering that subtree instead. This avoids trying to hydrate the mismatched subtree, but does not repair the underlying DOM difference and gives up hydration’s reuse benefits there. Consult Angular’s Hydration guide for the directive’s scope and use.
Prefer fixing the mismatch when practical. Consider skipping only the smallest affected component, and avoid applying it casually to the root application host because that can exclude a much larger subtree from hydration.
Rank #3
Fix the mismatch or skip hydration?
| Choice | When it fits | Trade-off |
|---|---|---|
| Fix the template, DOM behavior, or script timing | You can identify and change the source of the mismatch. | Preserves hydration for the corrected component and its descendants. |
Use ngSkipHydration on a component host |
A component cannot be made hydration-compatible immediately and a temporary workaround is needed. | The component and its children are re-rendered rather than hydrated, so they lose hydration’s DOM-reuse benefits. |
Before choosing the workaround, check whether the mismatch comes from markup you can correct or a dependency you can defer. If skipping is necessary, keep its scope narrow and revisit the underlying cause.
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.
