Hydration failed because the initial UI does not match what was rendered on the server – getStaticProps page after backup restoration

Solution overview

Use an on‑demand ISR API route that calls res.revalidate (or res.revalidateTag) after a backup restoration. The route is protected by a secret token, serves stale HTML while regenerating, and therefore avoids a hydration mismatch.

Confirmed facts

• Next.js ≥12.2 provides res.revalidate(path) for on‑demand ISR; tag‑based res.revalidateTag(tag) is available from Next.js 13.
• When revalidation is triggered, Next.js continues to serve the previously generated HTML until the background regeneration finishes, preventing a client‑server UI mismatch.
• The revalidation secret must be kept server‑side; exposing it allows uncontrolled cache purges.

Likely explanation of the hydration failure

After the database backup is restored, the data used by getStaticProps changes, but the existing ISR cache still holds the old HTML. If the client receives the new data (e.g., via client‑side fetching) while the server still serves the stale HTML, the initial UI does not match what was rendered on the server, causing a hydration error.

Steps to implement safe on‑demand revalidation

1. Create an API route, e.g., pages/api/revalidate.ts (or app/api/revalidate/route.js for the App Router).
2. In the route handler, verify a secret token passed via query, header, or body against an environment variable (process.env.REVALIDATE_SECRET).
3. If the token is valid, call res.revalidate('/blog/[slug]') for a specific path or res.revalidateTag('blog') if you have tagged the pages in getStaticProps.
4. Return a 200 response on success; otherwise return 401/400.
5. Secure the route: never log the secret, restrict to internal networks or add IP‑allowlist if needed.
6. After a backup restoration, invoke the endpoint from your restore script (e.g., curl -X POST "https://example.com/api/revalidate?secret=…&path=/blog/post-1" or a tag‑based call).
7. Optionally, set revalidate: false in getStaticProps to rely solely on on‑demand triggers, or keep a long background interval and use the endpoint for immediate refresh.

Missing diagnostic detail

To decide whether to use path‑based or tag‑based revalidation, please confirm: Do you have a consistent tag (e.g., 'blog') applied to all pages that need invalidation, or must you target individual dynamic routes? Knowing this will determine if a single tag‑based call suffices or if you need to enumerate paths.