Fix Hydration Error: Text content does not match server-rendered HTML in Next.js

This error occurs when the HTML rendered on the server differs from what React generates on the client during hydration. Common causes include using Date.now(), browser-only APIs, or invalid HTML nesting. Fix it by ensuring deterministic rendering or using useEffect for client-only content and suppressHydrationWarning sparingly.

Reading the Stack Trace

Here's what each line means:

• Server: "April 10, 2026" Client: "April 10, 2026 10:32:15 AM": The server rendered a date string without time, but the client rendered it with time, causing a text mismatch.
• at Timestamp (webpack-internal:///./src/components/Timestamp.tsx:6:10): The Timestamp component at line 6 produces different output on server vs client due to time-dependent rendering.
• at throwOnHydrationMismatch: React detected the mismatch and threw an error instead of silently recovering, which is the default behavior in React 18.

Common Causes

export default function Timestamp() {
  const now = new Date().toLocaleString();
  return <span>{now}</span>;
}

export default function Card({ children }) {
  return (
    <p>
      <div className="card">{children}</div>
    </p>
  );
}

export default function ThemeToggle() {
  const theme = typeof window !== 'undefined'
    ? localStorage.getItem('theme') || 'light'
    : 'light';
  return <button>{theme === 'dark' ? 'Light Mode' : 'Dark Mode'}</button>;
}

The Fix

Defer time-dependent rendering to useEffect, which only runs on the client after hydration completes. The server and initial client render both show the same loading state, preventing any mismatch.

export default function Timestamp() {
  const now = new Date().toLocaleString();
  return <span>{now}</span>;
}

import { useEffect, useState } from 'react';

export default function Timestamp() {
  const [now, setNow] = useState<string | null>(null);

  useEffect(() => {
    setNow(new Date().toLocaleString());
  }, []);

  if (!now) return <span>Loading...</span>;
  return <span>{now}</span>;
}

Testing the Fix

import { render, screen, act } from '@testing-library/react';
import Timestamp from './Timestamp';

describe('Timestamp', () => {
  it('shows loading state initially', () => {
    render(<Timestamp />);
    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  it('renders the current time after mount', async () => {
    jest.useFakeTimers();
    jest.setSystemTime(new Date('2026-01-15T10:30:00'));

    render(<Timestamp />);

    await act(async () => {
      jest.runAllTimers();
    });

    expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
    expect(screen.getByText(/2026/)).toBeInTheDocument();

    jest.useRealTimers();
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/hydration-mismatch-timestamp,git add src/components/Timestamp.tsx src/components/__tests__/Timestamp.test.tsx,git commit -m "fix: defer time-dependent rendering to useEffect to prevent hydration mismatch",git push origin fix/hydration-mismatch-timestamp

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npm run build

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

import { initBugStack } from 'bugstack-sdk'

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Run the test suite locally to confirm no hydration warnings appear.
2. Open a pull request with the useEffect-based rendering fix.
3. Wait for CI checks including the Next.js build to pass.
4. Have a teammate review and approve the PR.
5. Merge to main and verify no hydration errors appear in the browser console in staging.

Frequently Asked Questions