facebook/react · critical · Error

527

527

Error message

Incompatible React versions: The "react" and "react-dom" packages must have the exact same version. Instead got:
  - react:      ${isomorphicReactPackageVersion}
  - react-dom:  ${reactDOMPackageVersion}
Learn more: https://react.dev/warnings/version-mismatch

What it means

Every react-dom entry point (react-dom/client and all react-dom/server variants) calls ensureCorrectIsomorphicReactVersion at module initialization: it compares require('react').version with react-dom's own version and throws error 527 — listing both versions and a docs link — if they differ. React requires react and react-dom to be the exact same version because their internals (shared dispatchers, Flight/Fizz protocols) are tightly coupled, and the check runs at import time, before any render.

Source

Thrown at packages/react-dom/src/shared/ensureCorrectIsomorphicReactVersion.js:16

/**
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @flow
 */

import reactDOMPackageVersion from 'shared/ReactVersion';
import * as IsomorphicReactPackage from 'react';

export function ensureCorrectIsomorphicReactVersion() {
  const isomorphicReactPackageVersion = IsomorphicReactPackage.version;
  if (isomorphicReactPackageVersion !== reactDOMPackageVersion) {
    throw new Error(
      'Incompatible React versions: The "react" and "react-dom" packages must ' +
        'have the exact same version. Instead got:\n' +
        `  - react:      ${isomorphicReactPackageVersion}\n` +
        `  - react-dom:  ${reactDOMPackageVersion}\n` +
        'Learn more: https://react.dev/warnings/version-mismatch',
    );
  }
}

View on GitHub (pinned to eafeac097b)

Solutions

1. Install exact matching versions: npm install react@19.2.0 react-dom@19.2.0
2. Run npm ls react react-dom (or pnpm why react) to find duplicate copies, then fix with resolutions/overrides so one copy resolves
3. Delete node_modules and the lockfile entries and reinstall cleanly
4. If a dependency pins an incompatible react major, force alignment with npm overrides / yarn resolutions

Example fix

# before
$ npm ls react react-dom
├── react@19.2.0
└── react-dom@19.1.0   # mismatch → throws on import

# after
$ npm install react@19.2.0 react-dom@19.2.0

// Fail fast with a clear message BEFORE importing react-dom
import reactPkg from 'react/package.json';
import reactDomPkg from 'react-dom/package.json';

if (reactPkg.version !== reactDomPkg.version) {
  throw new Error(
    `react ${reactPkg.version} and react-dom ${reactDomPkg.version} must match — ` +
    'align versions before mounting'
  );
}

When it happens

Trigger: A dependency tree resolving react@19.2.0 alongside react-dom@19.1.0: partial manual upgrades, a transitive dependency pinning a different react, multiple react copies in node_modules, or using a canary react with a stable react-dom. The throw happens the moment react-dom/client or react-dom/server is imported.

Common situations: 'npm install react@latest' without updating react-dom; lockfile drift or dedupe failures producing duplicate copies; libraries bundling or aliasing their own react; monorepos with conflicting version ranges.

Related errors

• 599
• Invalid reference.
• Failed to read a RSC payload created by a development versio
• An unsupported type was passed to use(): ${String(usable)}
• Unknown Fiber. Needs to be a function component to inspect h

AI-assisted analysis of facebook/react@eafeac097b (2026-08-21). Data as JSON: /api/errors/d4acd014757330c6. Report an issue: GitHub.