diff --git a/aio/content/errors/NG0500.md b/aio/content/errors/NG0500.md index 542d66a4550..608e6636dc4 100644 --- a/aio/content/errors/NG0500.md +++ b/aio/content/errors/NG0500.md @@ -36,5 +36,7 @@ export class ExampleCmp { @debugging The error message in the developer console should contain information on a specific part of the application's DOM structure that is causing the problem. Review that part of the application for hydration-related errors, such as direct DOM manipulation using native APIs. - + You can add the `ngSkipHydration` attribute to your component host node as a possible workaround. + +If your application works in development environment, but you see hydration errors in production builds, make sure that the generated HTML that is delivered to a browser contains comment nodes produced by Angular during the rendering on the server. Those comment nodes are used by Angular runtime as anchors for view containers (with and without hydration) and hydration process expects them to be present at their original locations. If you have a custom logic to remove comment nodes from the HTML generated by the server-side rendering or you've configured your CDN to remove them before serving the content - disable the comment nodes removal and check if hydration errors are gone. diff --git a/aio/content/guide/hydration.md b/aio/content/guide/hydration.md index 48ada67ed42..bc40b6a72e0 100644 --- a/aio/content/guide/hydration.md +++ b/aio/content/guide/hydration.md @@ -71,7 +71,7 @@ You can confirm hydration is enabled by opening Developer Tools in your browser ## Constraints -Hydration imposes a few constraints on your application that are not present without hydration enabled. Ideally your application should have similar application structure (in terms of its DOM representation) on both the server and the client. The process of hydration expects the DOM tree to have the same structure in both places. +Hydration imposes a few constraints on your application that are not present without hydration enabled. Ideally your application should have similar application structure (in terms of its DOM representation) on both the server and the client. The process of hydration expects the DOM tree to have the same structure in both places. This also includes comment nodes that Angular produces during the rendering on the server: those nodes should be present in the HTML generated by the server-side rendering process. If there is a mismatch between server and client DOM tree structures, the hydration process will encounter problems attempting to match up what was expected to what is actually present in the DOM. Components that do direct DOM manipulation using native DOM APIs are the most common culprit.