{"record":{"id":"d4acd014757330c6","repo":"facebook/react","slug":"527","errorCode":"527","errorMessage":"Incompatible React versions: The \"react\" and \"react-dom\" packages must have the exact same version. Instead got:\n  - react:      ${isomorphicReactPackageVersion}\n  - react-dom:  ${reactDOMPackageVersion}\nLearn more: https://react.dev/warnings/version-mismatch","messagePattern":"Incompatible React versions: The \"react\" and \"react-dom\" packages must have the exact same version\\. Instead got:\n  - react:      (.+?)\n  - react-dom:  (.+?)\nLearn more: https://react\\.dev/warnings/version-mismatch","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/react-dom/src/shared/ensureCorrectIsomorphicReactVersion.js","lineNumber":16,"sourceCode":"/**\n * Copyright (c) Meta Platforms, Inc. and affiliates.\n *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n *\n * @flow\n */\n\nimport reactDOMPackageVersion from 'shared/ReactVersion';\nimport * as IsomorphicReactPackage from 'react';\n\nexport function ensureCorrectIsomorphicReactVersion() {\n  const isomorphicReactPackageVersion = IsomorphicReactPackage.version;\n  if (isomorphicReactPackageVersion !== reactDOMPackageVersion) {\n    throw new Error(\n      'Incompatible React versions: The \"react\" and \"react-dom\" packages must ' +\n        'have the exact same version. Instead got:\\n' +\n        `  - react:      ${isomorphicReactPackageVersion}\\n` +\n        `  - react-dom:  ${reactDOMPackageVersion}\\n` +\n        'Learn more: https://react.dev/warnings/version-mismatch',\n    );\n  }\n}\n","sourceCodeStart":1,"sourceCodeEnd":25,"githubUrl":"https://github.com/facebook/react/blob/eafeac097ba51e1eab809c07102126bd5f8e5425/packages/react-dom/src/shared/ensureCorrectIsomorphicReactVersion.js#L1-L25","documentation":"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.","triggerScenarios":"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.","commonSituations":"'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.","solutions":["Install exact matching versions: npm install react@19.2.0 react-dom@19.2.0","Run npm ls react react-dom (or pnpm why react) to find duplicate copies, then fix with resolutions/overrides so one copy resolves","Delete node_modules and the lockfile entries and reinstall cleanly","If a dependency pins an incompatible react major, force alignment with npm overrides / yarn resolutions"],"exampleFix":"# before\n$ npm ls react react-dom\n├── react@19.2.0\n└── react-dom@19.1.0   # mismatch → throws on import\n\n# after\n$ npm install react@19.2.0 react-dom@19.2.0","handlingStrategy":"validation","validationCode":"// Fail fast with a clear message BEFORE importing react-dom\nimport reactPkg from 'react/package.json';\nimport reactDomPkg from 'react-dom/package.json';\n\nif (reactPkg.version !== reactDomPkg.version) {\n  throw new Error(\n    `react ${reactPkg.version} and react-dom ${reactDomPkg.version} must match — ` +\n    'align versions before mounting'\n  );\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always install react and react-dom together at the same exact version","Add npm overrides / yarn resolutions pinning one react version across the dependency tree","Run npm ls react react-dom in CI to fail on duplicate or mismatched copies","Avoid mixing canary and stable channels between react and react-dom"],"tags":["react-dom","react","version-mismatch","npm","installation"],"backgroundTag":"react-react-dom-version-mismatch","analyzedSha":"eafeac097ba51e1eab809c07102126bd5f8e5425","analyzedAt":"2026-08-21T22:01:08.818Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}