{"record":{"id":"21e2c9b36688a902","repo":"withastro/astro","slug":"unsupported-react-version-majorversion-21e2c9","errorCode":null,"errorMessage":"Unsupported React version: ${majorVersion}.","messagePattern":"Unsupported React version: (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/integrations/react/src/index.ts","lineNumber":176,"sourceCode":"\t\t\t\t\tfinalOptions.optimizeDeps!.include.push(reactConfig.client);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn finalOptions;\n\t\t},\n\t};\n}\n\nexport default function ({\n\tinclude,\n\texclude,\n\tbabel,\n\texperimentalReactChildren,\n\texperimentalDisableStreaming,\n}: ReactIntegrationOptions = {}): AstroIntegration {\n\tconst majorVersion = getReactMajorVersion();\n\tif (!isSupportedReactVersion(majorVersion)) {\n\t\tthrow new Error(`Unsupported React version: ${majorVersion}.`);\n\t}\n\tconst versionConfig = versionsConfig[majorVersion];\n\n\treturn {\n\t\tname: '@astrojs/react',\n\t\thooks: {\n\t\t\t'astro:config:setup': ({ command, addRenderer, updateConfig, injectScript }) => {\n\t\t\t\taddRenderer(getRenderer(versionConfig));\n\t\t\t\tupdateConfig({\n\t\t\t\t\tvite: getViteConfiguration(\n\t\t\t\t\t\t{ include, exclude, babel, experimentalReactChildren, experimentalDisableStreaming },\n\t\t\t\t\t\tversionConfig,\n\t\t\t\t\t),\n\t\t\t\t});\n\t\t\t\tif (command === 'dev') {\n\t\t\t\t\tconst preamble = FAST_REFRESH_PREAMBLE.replace(`__BASE__`, '/');\n\t\t\t\t\tinjectScript('before-hydration', preamble);\n\t\t\t\t}","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/integrations/react/src/index.ts#L158-L194","documentation":"Thrown at @astrojs/react integration setup (`astro:config:setup` predecessor) when the resolved React major version is not supported (must be 17, 18, or 19). This fires during config load, before any rendering, so the build/dev server never starts.","triggerScenarios":"Loading `@astrojs/react` in `astro.config` integrations while the workspace has React 16, a broken install, or conflicting React versions that cause `getReactMajorVersion()` to return NaN or an unsupported number.","commonSituations":"A monorepo hoist that pulls React 16 into the Astro app. Mixing `react` and `react-dom` majors. A stale lockfile after a partial React downgrade.","solutions":["Install a supported React major: `pnpm add react@19 react-dom@19`.","Run `pnpm why react` / `npm ls react` to find and resolve duplicate or mismatched versions.","Regenerate the lockfile (`pnpm install --force` / delete `node_modules` + lockfile) if versions look correct but resolution is wrong."],"exampleFix":"// before: mismatched majors\npnpm add react@18 react-dom@19\n// after\npnpm add react@19 react-dom@19","handlingStrategy":"type-guard","validationCode":"import { getReactMajorVersion, isSupportedReactVersion } from '@astrojs/react/version';\nconst major = getReactMajorVersion();\nif (!isSupportedReactVersion(major)) {\n  throw new Error(`Unsupported React ${major}; install 17/18/19 before 'astro dev'.`);\n}","typeGuard":"function isSupportedReactMajor(v: number): v is 17 | 18 | 19 {\n  return [17, 18, 19].includes(v);\n}","tryCatchPattern":null,"preventionTips":["Lock React and React-DOM to identical majors in package.json.","Add a CI step asserting the resolved React major is supported.","Reinstall from a clean lockfile after React upgrades."],"tags":["react","integration","version","config","peer-dependency"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}