This error means that during the hydration process, Angular expected a DOM structure as rendered and annotated during server-side rendering. However, on the client, the DOM tree was different than the server rendered DOM tree.
This error typically happens due to direct DOM manipulation using native browser APIs that alter the DOM structure outside of what Angular produced. It will also occur if you use innerHTML or outerHTML to set HTML content, which similarly alters the DOM structure outside of what Angular produced. You can resolve this by refactoring the component to use native Angular APIs instead of native APIs. If that's not possible, you can add the ngSkipHydration attribute to your component's host node, which will disable hydration for the component and its children. ngSkipHydration should only be used as a last resort and should be considered a bug that needs to be fixed.
More information about hydration can be found in this guide.
The following example will trigger the error.
@Component({ selector: 'app-example', template: '<div><span>world</span></div>',})export class ExampleComponent { hostElement = inject(ElementRef).nativeElement; ngOnInit() { // Create a new <p> element with the `Hello` text inside const newNode = document.createElement('p'); newNode.innerHTML = 'Hello'; // Insert the <p> before the first element. Since Angular has no information // about the <p> element, it will be looking for the <div> element at the first // element position instead. As a result, a hydration mismatch error would be // thrown. Instead, update component's template to create the <p> element. this.hostElement.insertBefore(newNode, this.hostElement.firstChild); }}
Debugging the error
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.
Check that your template has valid HTML structure. See more information in the hydration guide.
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.