withastro/astro · error · Error

Unable to resolve

Error message

Unable to resolve "${packageInfo.name}"

What it means

The `@astrojs/upgrade` tool fetches package metadata from the npm registry (`GET {registry}/{name}`) to read dist-tags for each package it plans to upgrade. Any HTTP status >= 400 aborts with "Unable to resolve \"<package>\"". The error deliberately hides the status code; it means the registry lookup for that package name failed.

Solutions

1. Check connectivity and the package exists: `npm view <package> dist-tags --registry <registry>`
2. If you use a private registry, ensure you are authenticated (`npm whoami`) and the package is mirrored/published there
3. Pass the correct registry: `npx @astrojs/upgrade --registry https://registry.npmjs.org/`
4. If the failure is transient network flakiness, simply rerun the upgrade

async function registryHasPackage(registry: string, name: string): Promise<boolean> {
  const res = await fetch(`${registry}/${name}`, { method: 'HEAD' });
  return res.status < 400;
}

for (let attempt = 0; attempt < 3; attempt++) {
  try {
    await runUpgrade();
    break;
  } catch (e) {
    if (e instanceof Error && e.message.startsWith('Unable to resolve') && attempt < 2) continue;
    throw e;
  }
}

When it happens

Trigger: Running `npx @astrojs/upgrade` (or `astro upgrade`) when a target package does not exist on the configured registry (404), the registry requires auth for it (401/403), or the network/proxy blocks the request (5xx). Also when `--registry` points at a mirror that lacks the package.

Common situations: Corporate npm proxy or private registry (Artifactory/Verdaccio) that hasn't cached the package; offline or DNS-broken environments; package name taken from a fork or internal alias that was never published; typo'd registry URL.

Related errors

• [astro:cache] Background revalidation failed for
• Be sure to follow the
• CannotFetchFontFile
• `markdown.remarkPlugins`, `markdown.rehypePlugins`, and…
• Process exited with code

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

Appendix: source

Thrown at packages/upgrade/src/actions/verify.ts:147

		return false;
	}
	for (const packageInfo of ctx.packages) {
		if (!packageInfo.targetVersion) {
			return false;
		}
	}
	return true;
}

export async function resolveTargetVersion(
	packageInfo: PackageInfo,
	registry: string,
): Promise<void> {
	const packageMetadata = await fetch(`${registry}/${packageInfo.name}`, {
		headers: { accept: 'application/vnd.npm.install-v1+json' },
	});
	if (packageMetadata.status >= 400) {
		throw new Error(`Unable to resolve "${packageInfo.name}"`);
	}
	const { 'dist-tags': distTags } = await packageMetadata.json();
	let version = distTags[packageInfo.targetVersion];
	if (version) {
		const currentCoerced = semverCoerce(packageInfo.currentVersion);
		const targetParsed = semverParse(version);
		// If the dist-tag points to a version older than the installed one, fall back to latest.
		if (currentCoerced && targetParsed && semverGt(currentCoerced, targetParsed)) {
			packageInfo.targetVersion = 'latest';
			version = distTags.latest;
		} else {
			packageInfo.tag = packageInfo.targetVersion;
			packageInfo.targetVersion = version;
		}
	} else {
		packageInfo.targetVersion = 'latest';
		version = distTags.latest;
	}

View on GitHub (pinned to 52e6c34790)