withastro/astro · error · Error

Unsupported React version

Error message

Unsupported React version: ${majorVersion}.

What it means

The @astrojs/react integration itself resolves react-dom's version at import/creation time and looks it up in versionsConfig (React 17, 18, 19 only) to pick matching client/server entrypoints. An unsupported major throws before any hook runs, so astro dev/build fails during config setup.

Solutions

1. Pin both react and react-dom to a supported major (17, 18, or 19), keeping them on the same version
2. Reinstall to fix lockfile drift: remove node_modules and the lockfile entry, then fresh install
3. Update @astrojs/react for support of newer React majors as they land

Example fix

# before
react@16 react-dom@16
# after
react@^18 react-dom@^18

import { version } from 'react-dom';
const major = Number(/\d+\./.exec(version)?.[0]);
if (![17, 18, 19].includes(major)) {
  throw new Error(`Fix react-dom before building: got ${version}, need 17/18/19`);
}

function isSupportedReactMajor(major: number): major is 17 | 18 | 19 {
  return major in { 17: 1, 18: 1, 19: 1 };
}

When it happens

Trigger: Starting astro dev or astro build with react-dom 16, an experimental major, or react-dom missing (version parse yields NaN); mixed react/react-dom versions where the resolved react-dom is unsupported.

Common situations: Upgrading to a brand-new React major before the adapter supports it; lockfile drift after a partial upgrade; CI installing react only; workspace hoisting an old react-dom.

Related errors

• `Astro.session` was accessed but no session storage is…
• More than one JSX renderer is enabled. This will lead to…
• More than one JSX renderer is enabled. This will lead to…
• [preview] No adapter found.
• Setting the 'mode' option is required.

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/21e2c9b36688a902. Report an issue: GitHub.

Appendix: source

Thrown at packages/integrations/react/src/index.ts:176

					finalOptions.optimizeDeps!.include.push(reactConfig.client);
				}
			}

			return finalOptions;
		},
	};
}

export default function ({
	include,
	exclude,
	babel,
	experimentalReactChildren,
	experimentalDisableStreaming,
}: ReactIntegrationOptions = {}): AstroIntegration {
	const majorVersion = getReactMajorVersion();
	if (!isSupportedReactVersion(majorVersion)) {
		throw new Error(`Unsupported React version: ${majorVersion}.`);
	}
	const versionConfig = versionsConfig[majorVersion];

	return {
		name: '@astrojs/react',
		hooks: {
			'astro:config:setup': ({ command, addRenderer, updateConfig, injectScript }) => {
				addRenderer(getRenderer(versionConfig));
				updateConfig({
					vite: getViteConfiguration(
						{ include, exclude, babel, experimentalReactChildren, experimentalDisableStreaming },
						versionConfig,
					),
				});
				if (command === 'dev') {
					const preamble = FAST_REFRESH_PREAMBLE.replace(`__BASE__`, '/');
					injectScript('before-hydration', preamble);
				}

View on GitHub (pinned to 52e6c34790)