withastro/astro · critical · Error

Unsupported React version: ${majorVersion}.

Error message

Unsupported React version: ${majorVersion}.

What it means

Thrown by `getContainerRenderer()` in @astrojs/react when the installed React major version is not in the supported set (17, 18, or 19 per `versionsConfig`). The container renderer needs version-specific server/client entrypoints that only exist for those majors.

Source

Thrown at packages/integrations/react/src/container-renderer.ts:20

import {
	getReactMajorVersion,
	isSupportedReactVersion,
	type ReactVersionConfig,
	versionsConfig,
} from './version.js';

export function getRenderer(reactConfig: ReactVersionConfig): AstroRenderer {
	return {
		name: '@astrojs/react',
		clientEntrypoint: reactConfig.client,
		serverEntrypoint: reactConfig.server,
	};
}

export function getContainerRenderer(): AstroRenderer {
	const majorVersion = getReactMajorVersion();
	if (!isSupportedReactVersion(majorVersion)) {
		throw new Error(`Unsupported React version: ${majorVersion}.`);
	}
	return getRenderer(versionsConfig[majorVersion]);
}

View on GitHub (pinned to d081033d5f)

Solutions

1. Pin React and React-DOM to a supported major: `pnpm add react@18 react-dom@18` (or 17/19).
2. Ensure both `react` and `react-dom` resolve to the same major; run `npm ls react react-dom` to check for duplicates.
3. If you need a newer React, upgrade @astrojs/react to a version that adds it to `versionsConfig`.

Example fix

// before: react@16 installed
// after
pnpm add react@18 react-dom@18

import { getReactMajorVersion, isSupportedReactVersion } from '@astrojs/react/version';
const major = getReactMajorVersion();
if (!isSupportedReactVersion(major)) {
  throw new Error(`Install React 17, 18, or 19 (got ${major}).`);
}

function isSupportedReact(major: number): major is 17 | 18 | 19 {
  return major === 17 || major === 18 || major === 19;
}

When it happens

Trigger: Calling `getContainerRenderer()` with React 16 or older, a pre-release/RC of an unreleased major (e.g. React 20 alpha), or when `react-dom`'s `version` export cannot be parsed (NaN major).

Common situations: Installing React 16 alongside @astrojs/react. A peer-dependency resolution that pulled in a mismatched React. Using a canary React build whose version string doesn't match `/\d+\./`.

Related errors

• Unsupported React version: ${majorVersion}.
• The renderer you passed isn't valid. A renderer is usually a
• The renderer name must be provided when adding a server rend
• You tried to add the ${name} client renderer, but its server
• Couldn't find component for route ${routeData.pathname}

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