Be sure to follow the ${pluralize('CHANGELOG', majors.length

Error message

Be sure to follow the ${pluralize('CHANGELOG', majors.length)}.

What it means

This is not an error: `astro upgrade` prints it after you confirm upgrading packages that cross a major version (packages/upgrade/src/actions/install.ts:74). The tool detects major bumps in the packages it is about to install, prompts '... breaking changes. Continue?', and on 'yes' emits `warn('check', 'Be sure to follow the CHANGELOG(s).')` followed by each package's changelog title and URL (e.g. astro, @astrojs/mdx). It exists because majors of Astro packages routinely contain breaking config or API changes, and skipping the changelog is the top cause of broken upgrades.

Source

Thrown at packages/upgrade/src/actions/install.ts:74

	}
	if (majors.length > 0) {
		const { proceed } = await ctx.prompt({
			name: 'proceed',
			type: 'confirm',
			label: title('wait'),
			message: `${pluralize(
				['One package has', 'Some packages have'],
				majors.length,
			)} breaking changes. Continue?`,
			initial: true,
		});
		if (!proceed) {
			return ctx.exit(0);
		}

		newline();

		await warn('check', `Be sure to follow the ${pluralize('CHANGELOG', majors.length)}.`);
		for (const pkg of majors.sort(sortPackages)) {
			await changelog(pkg.name, pkg.changelogTitle!, pkg.changelogURL!);
		}
	}

	newline();
	if (ctx.dryRun) {
		await info('--dry-run', `Skipping dependency installation`);
	} else {
		await runInstallCommand(ctx, dependencies, devDependencies, shellFn);
	}
}

function filterPackages(ctx: Pick<Context, 'packages'>) {
	const current: PackageInfo[] = [];
	const dependencies: PackageInfo[] = [];
	const devDependencies: PackageInfo[] = [];
	for (const packageInfo of ctx.packages) {

View on GitHub (pinned to 52e6c34790)

Solutions

Open each printed changelog URL and apply the migration steps for the majors you crossed before running the app (Astro maintains per-major upgrade guides linked at the top of each changelog).
If you were not ready for breaking changes, re-run `astro upgrade` and answer 'no' at the confirm prompt (or Ctrl+C) — it exits 0 without installing; or upgrade selectively with `astro upgrade astro@4` style pins.
Use `astro upgrade --dry-run` first to preview which packages are majors and read the changelogs before committing to the install.
After upgrading, run `astro build`/your test suite immediately to surface breaking changes rather than discovering them at deploy time.

Defensive patterns

Strategy: validation

Prevention

Run `astro upgrade --dry-run` first to see which packages cross majors, then read the linked changelogs before answering the confirm prompt.
Read Astro's official upgrade guide for each major you cross (linked from the changelog) — most upgrade breakages are config/API migrations documented there.
Upgrade in a clean git branch with all tests green before and after, so breaking changes surface as diffs rather than production incidents.
Answer 'no' at the breaking-changes prompt to abort cost-free if you haven't reviewed the changelogs yet; nothing is installed until you confirm.

When it happens

Trigger: Running `npx astro upgrade` (or the integrated upgrade command) when at least one outdated dependency has `isMajor: true` — i.e. the latest version's major is greater than the installed one (astro 4→5, @astrojs/vue 4→5) — and answering the confirm prompt affirmatively. Immediately after, the changelog links for each major package are printed, then the installer proceeds (or is skipped with --dry-run, which still prints the warn).

Common situations: Upgrading across Astro major releases (e.g. 4.x → 5.x) where astro and several @astrojs/* integrations jump majors together; running `astro upgrade` in a CI or scripted environment where the changelog output is piped away and never read; maintaining a starter template whose many integrations all bump majors at once.

Related errors

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