withastro/astro · critical · Error

Unsupported React version: ${majorVersion}.

Error message

Unsupported React version: ${majorVersion}.

What it means

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.

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 d081033d5f)

Solutions

1. Install a supported React major: `pnpm add react@19 react-dom@19`.
2. Run `pnpm why react` / `npm ls react` to find and resolve duplicate or mismatched versions.
3. Regenerate the lockfile (`pnpm install --force` / delete `node_modules` + lockfile) if versions look correct but resolution is wrong.

Example fix

// before: mismatched majors
pnpm add react@18 react-dom@19
// after
pnpm add react@19 react-dom@19

import { getReactMajorVersion, isSupportedReactVersion } from '@astrojs/react/version';
const major = getReactMajorVersion();
if (!isSupportedReactVersion(major)) {
  throw new Error(`Unsupported React ${major}; install 17/18/19 before 'astro dev'.`);
}

function isSupportedReactMajor(v: number): v is 17 | 18 | 19 {
  return [17, 18, 19].includes(v);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unsupported React version: ${majorVersion}.
• CONTENT_TOO_LARGE
• Configured image service is not a local service
• Configured image service is not a local service
• MissingGetFontFileRequestUrl

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