What causes "Unsupported React version: ${majorVersion}." in withastro/astro?

Pin react and react-dom to a supported major, e.g. pnpm add react@^19 react-dom@^19

withastro/astro · error · Error

Unsupported React version

Error message

Unsupported React version: ${majorVersion}.

What it means

getContainerRenderer() (used with Astro's Container API to render components in tests/SDKs) resolves the installed react-dom version and looks it up in versionsConfig, which contains entries for React 17, 18, and 19 only. Any other major (older, canary, or unresolvable yielding NaN) throws before a renderer can be constructed.

Solutions

Pin react and react-dom to a supported major, e.g. pnpm add react@^19 react-dom@^19
Make sure react-dom is actually installed; the version is read from it, not react
Update @astrojs/react to the latest release to pick up support for newer majors

Example fix

# before
react@canary react-dom@canary
# after
react@^19 react-dom@^19

Defensive patterns

Strategy: type-guard

Validate before calling

import { version } from 'react-dom';
const SUPPORTED = new Set([17, 18, 19]);
const major = Number(/\d+\./.exec(version)?.[0].replace('.', ''));
if (!SUPPORTED.has(major)) throw new Error(`react-dom ${version} is unsupported; pin to 17/18/19`);

Type guard

const SUPPORTED_REACT_MAJORS = new Set([17, 18, 19]);
function isSupportedReactMajor(major: number): major is 17 | 18 | 19 {
  return SUPPORTED_REACT_MAJORS.has(major);
}

Prevention

Pin react and react-dom to the same supported major in every workspace
Assert the version in test setup before calling getContainerRenderer()
Treat NaN majors as a missing react-dom dependency and fail the run early

When it happens

Trigger: Running container-based tests with react-dom 16 or an experimental/canary build; react-dom not installed so getReactMajorVersion returns NaN; a monorepo where the test resolves a different react-dom than the app.

Common situations: Trying React canary/next-major features before @astrojs/react supports them; installing react but not react-dom; hoisting/resolution issues in workspaces picking an old react-dom.

Related errors

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

Appendix: 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 52e6c34790)