Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsAngular’s NG0502: Hydration Missing Node means hydration expected a DOM node at a particular location but could not find it. The server-rendered page and the browser DOM no longer match where Angular is trying to reuse the server output. Compare those two DOM states, then check for code or scripts that changed the page, invalid HTML nesting, or inconsistent whitespace settings. Fix the mismatch if possible; skipping hydration is a limited workaround, not a general repair.
What NG0502 means
During hydration, Angular reuses DOM created by server-side rendering rather than building the entire page from scratch. It expects the browser’s DOM structure to match the server-rendered structure. NG0502 reports that an expected node is missing at a particular position. It belongs to the broader family of hydration node mismatch errors; Angular’s NG0502 reference points to NG0500 for additional debugging guidance.
As an Amazon Associate I earn from qualifying purchases.
The error code alone does not identify the missing node, component, template, or script. Finding the cause requires inspecting the affected route’s server output, the DOM when hydration starts, and code that can change that DOM.
How to find the mismatch
- Reproduce it on the affected route. Note the browser console error and which part of the page appears affected. The NG0502 reference directs developers to NG0500’s debugging information; it does not name the responsible node for your application.
- Compare server HTML with the browser DOM at hydration time. Inspect the HTML returned by server-side rendering and the DOM in the browser before Angular hydrates it. Look for nodes, comments, or whitespace that are missing, inserted, or moved. Angular’s hydration guide explains that the server-rendered DOM must not be altered before hydration.
- Trace code that manipulates the DOM. Search the affected component and its dependencies for native DOM operations such as
documentqueries,appendChild, node removal or movement, and assignments toinnerHTMLorouterHTML. These can put the browser DOM in a state Angular does not expect. - Validate the template’s HTML structure. Check whether the browser is correcting invalid markup as it parses it. Angular specifically advises declaring a
<tbody>in tables and avoiding a<div>inside a<p>; nested anchors are another invalid structure to check. - Check scripts that run before hydration. A third-party script, including analytics code, may insert, remove, or move nodes before Angular starts. Where feasible, defer page-mutating scripts until after hydration, for example with Angular’s
AfterNextRenderguidance. - Review whitespace configuration if the structure still differs. Angular recommends the default
preserveWhitespaces: false. If whitespace preservation is enabled, keep that setting consistent in server and browser builds. This is one possible contributor, not a diagnosis for every NG0502.
Fix the source of the DOM change
Use Angular rendering patterns instead of native DOM changes
When application code creates or changes content, prefer Angular-supported template and rendering approaches over direct DOM manipulation. This lets Angular keep the rendered structure consistent with the structure it expects to hydrate. Revisit operations such as moving existing nodes or replacing a block through innerHTML; correcting the code that changes the DOM is preferable to suppressing the symptom.
#1 Best Overall
Make the template valid and explicit
Correct invalid nesting so the browser does not silently produce a different tree from the one implied by the template. For tables, include the <tbody> explicitly. Keep block elements such as <div> out of paragraphs, and do not nest anchors.
Delay scripts that mutate the page
If a dependency or third-party script modifies the DOM before Angular hydrates, determine whether it can run later. Angular recommends deferring such work until after hydration where possible; its hydration guide describes using AfterNextRender as an example.
When to use ngSkipHydration
If an incompatible component cannot be refactored immediately, Angular’s ngSkipHydration can be a temporary, narrowly scoped workaround. It must be applied to a component host. Angular skips hydration for that component and its children, destroying and re-rendering that subtree instead of reusing the server-rendered DOM. That can restore operation in the short term, but the subtree loses hydration’s reuse benefits. It does not fix the underlying mismatch, and it should not be placed on arbitrary elements or casually on the root application host. See Angular’s guidance on hydration and ngSkipHydration.
Choose between correction and a temporary workaround
| Option | Use it when | Trade-off |
|---|---|---|
| Correct the DOM behavior or markup | You can identify and change the code, template, or script that causes the mismatch. | Preserves hydration for the component. |
| Defer a page-mutating script | A script changes the DOM before Angular hydrates and can run later. | Requires the script’s behavior to remain valid when delayed. |
Apply ngSkipHydration to a component host |
The component cannot be made hydration-compatible immediately. | Angular re-renders that component and its descendants instead of hydrating them; this is a workaround, not a mismatch fix. |
Prefer the smallest correction that restores a consistent server and browser DOM. The appropriate choice depends on where the mismatch originates and whether its cause can be changed or delayed.
Quick Recap
Rank #3
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.
