withastro/astro · info

update ▶ New version of Astro available: ${latestVersion} Ru

Error message

update ▶ New version of Astro available: ${latestVersion}
Run ${execCommand.command} ${execCommand.args.join(' ')} to update

What it means

On dev-server start, Astro asynchronously checks the registry for a newer release. If the installed version is behind by a whole minor/major, or by MAX_PATCH_DISTANCE or more patch versions within the same minor, it prints this upgrade notice with the exact update command for your package manager. Registry failures are swallowed — this never blocks startup.

Source

Thrown at packages/astro/src/core/dev/dev.ts:77

					if (shouldCheck) {
						const version = await fetchLatestAstroVersion(restart.container.settings.preferences);

						if (gt(version, currentVersion)) {
							// Only update the latestAstroVersion if the latest version is greater than the current version, that way we don't need to check that again
							// whenever we check for the latest version elsewhere
							restart.container.settings.latestAstroVersion = version;

							const sameMajor = major(version) === major(currentVersion);
							const sameMinor = minor(version) === minor(currentVersion);
							const patchDistance = patch(version) - patch(currentVersion);

							if (sameMajor && sameMinor && patchDistance < MAX_PATCH_DISTANCE) {
								// Don't bother the user with a log if they're only a few patch versions behind
								// We can still tell them in the dev toolbar, which has a more opt-in nature
								return;
							}

							logger.warn(
								'SKIP_FORMAT',
								await newVersionAvailable({
									latestVersion: version,
								}),
							);
						}
					}
				})
				.catch(() => {});
		} catch {
			// Just ignore the error, we don't want to block the dev server from starting and this is just a nice-to-have feature
		}
	}

	let store: MutableDataStore | undefined;
	try {
		const chunkSize = getDataStoreChunkSize(restart.container.settings);
		if (chunkSize !== undefined) {

View on GitHub (pinned to e294953aa8)

Solutions

1. Run the exact command shown in the message (e.g. `npx @astrojs/upgrade` or the npm/pnpm install line)
2. Review the Astro CHANGELOG for breaking changes before jumping a major
3. Ignore it if you are intentionally pinned — it is informational only

Example fix

# before: astro@5.0.2 installed, 5.1.0 is latest

# after — run the command the warning prints
npx @astrojs/upgrade
# or explicitly:
npm install astro@latest

// CI: flag when astro is a minor/major behind latest
import { execSync } from 'node:child_process';
const installed = JSON.parse(execSync('npm ls astro --json').toString()).dependencies.astro.version;
const latest = execSync('npm view astro version').toString().trim();
if (installed.split('.').slice(0, 2).join('.') !== latest.split('.').slice(0, 2).join('.')) {
  console.warn(`astro ${installed} is behind latest ${latest}`);
}

When it happens

Trigger: Running `astro dev` when the published latest version differs in major or minor from the installed one, or the installed patch trails the latest patch by MAX_PATCH_DISTANCE or more.

Common situations: Projects pinned to an older Astro major; appearing shortly after a new release ships; offline or proxy-restricted environments simply never see it.

Related errors

• Unexpectedly unable to find a component instance for route $
• Astro couldn't find the correct page to render, probably bec
• Unexpectedly unable to find a component instance for route $
• Astro couldn't find the correct page to render, probably bec
• No cached compile metadata found for "${id}". The main Astro

AI-assisted analysis of withastro/astro@e294953aa8 (2026-08-18). Data as JSON: /api/errors/14f7129d86e3ef84. Report an issue: GitHub.