🔍 What is hydration detection?
Next.js can render page content on the server and then make it interactive in the browser. This process is called hydration. OTTO’s hydration detection checks whether a page is still being hydrated before applying changes that may update the page’s HTML.
The hydration warning means Search Atlas detected a framework that re-renders the page in the browser, such as Next.js or React. With a Cloudflare installation, this can remove the OTTO tag. If the tag still survives, the warning is advisory, and the client-side OTTO integration is the recommended installation method. If the status is a failure (the tag was removed during hydration, or two OTTO installations were found), follow the recommendation shown in the check.
🛡️ Is OTTO safe for Next.js sites?
Yes. OTTO can run on Next.js and React websites when it is installed through the recommended client-side integration. The integration loads in the browser, allowing Next.js to complete hydration before OTTO processes applicable changes.
As with any tool that updates page content, avoid adding the OTTO script inside React-rendered markup or changing the same elements with custom client-side code. These practices can cause unexpected rendering or hydration behavior.
⚙️ Recommended client-side setup
- Install the OTTO integration using the code or setup instructions provided in the Search Atlas platform.
- Add the integration to your global client-side layout, document, or approved script area—not inside a component that renders changing page content.
- Add the OTTO pixel script once in the shared root layout (
app/layout, or\_document/\_app), just before, so it loads on every page. Don't place it inside a component that renders changing page content. - Deploy the change to a staging environment first, if available.
- Confirm that pages load normally and that navigation, forms, menus, and other interactive elements continue to work.
✅ How to verify the integration
- Open the affected page in a private browser window.
- Wait until the page finishes loading and interactive elements respond normally.
- In the OTTO installation guide, click **Scan** to confirm detection, then **Run Diagnostics** for details. A failed Scan means the installation isn't complete. Recheck script placement, the project UUID, and that the script loads on the live site. In browser DevTools,
#sa-dynamic-optimizationshould be present with yourdata-uuid, thedynamic\_optimizationscript should return HTTP 200, andwindow.SA\_loadedshould betrue. - Test both a direct page load and navigation to the page from another route, because Next.js may handle these differently.
- Review the page source and browser console only if verification does not complete. Look for duplicate scripts, blocked requests, or hydration errors.
🧩 Preventing hydration conflicts
- Do not place OTTO code inside a server component unless your Next.js implementation specifically supports that use.
- Do not render OTTO conditionally based on values that differ between the server and browser.
- Do not add the integration more than once through multiple layouts, components, or tag managers.
- Keep custom React code from immediately overwriting the same content OTTO is expected to manage.
- Test pages that use dynamic content, personalization, or client-side navigation.
🚦If the warning remains
The hydration warning can remain visible as long as Search Atlas detects a framework such as Next.js or React, even when the OTTO tag currently survives. If the page works and Scan succeeds, no action is required, though the client-side integration is the recommended installation method. If the check shows a failure (the tag was removed during hydration, or two installations were found), follow its recommendation.
If verification fails, check that the script is present on the published site, is not blocked by a content security policy or consent tool, and is loaded only once. Also confirm that recent deployments did not move or remove the integration.
If you need further assistance, open the chat widget in the bottom-right corner of the platform and send your message. A member of our support team will reply in the chat.