payloadcms/payload · error · Error

No version or tag "${version}" found for package: ${packageN

Error message

No version or tag "${version}" found for package: ${packageName}

What it means

resolvePackageVersion first checks npm dist-tags; if the supplied versionOrTag is not a dist-tag, it verifies it as an explicit version via the registry package endpoint and throws on non-200. Covers typos in both tags and explicit semver.

Source

Thrown at packages/create-payload-app/src/utils/resolvePackageVersion.ts:66

  }
  return versionOrTag
}

async function fetchDistTags(packageName: string): Promise<Record<string, string>> {
  const response = await fetch(`https://registry.npmjs.org/-/package/${packageName}/dist-tags`)
  return (await response.json()) as Record<string, string>
}

async function verifyVersionExists({
  packageName,
  version,
}: {
  packageName: string
  version: string
}): Promise<void> {
  const response = await fetch(`https://registry.npmjs.org/${packageName}/${version}`)
  if (response.status !== 200) {
    throw new Error(`No version or tag "${version}" found for package: ${packageName}`)
  }
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Use a known dist-tag: `--payload-version latest` or `--payload-version canary`.
2. If specifying a concrete version, copy the exact string from https://registry.npmjs.org/payload (no leading 'v').
3. Check connectivity to https://registry.npmjs.org and any configured registry mirror.
4. For @payloadcms/* packages, confirm the version exists for that specific package.

Example fix

// before
$ npx create-payload-app . --payload-version v3.40.0

// after
$ npx create-payload-app . --payload-version 3.40.0

async function resolveOrFail(pkg: string, tagOrVersion: string) {
  const tagsRes = await fetch(`https://registry.npmjs.org/-/package/${pkg}/dist-tags`)
  const tags = await tagsRes.json()
  if (tags[tagOrVersion]) return tags[tagOrVersion]
  const verRes = await fetch(`https://registry.npmjs.org/${pkg}/${tagOrVersion}`)
  if (verRes.status !== 200) {
    throw new Error(`${pkg}@${tagOrVersion} is neither a dist-tag nor a published version`)
  }
  return tagOrVersion
}

const DIST_TAGS = ['latest', 'canary', 'next', 'beta'] as const
function isDistTag(x: string): x is (typeof DIST_TAGS)[number] {
  return (DIST_TAGS as readonly string[]).includes(x)
}
function isSemver(x: string): boolean {
  return /^\d+\.\d+\.\d+(-[\w.]+)?$/.test(x)
}

When it happens

Trigger: Passing --payload-version (or packageName@version) with a value that is neither a published dist-tag (latest, canary) nor a published concrete version, e.g. '3.40', 'v3.40.0', or a yanked version. Also thrown if the registry returns non-200 due to offline/404.

Common situations: Typo in version (leading 'v', partial semver, wrong patch); using a version from a different major not yet published; corporate registry mirror missing the version; transient npm outage.

Related errors

• Failed to download: ${url}
• Failed to download: ${url}
• Invalid template given
• Invalid database type given. Valid types are: ${Object.value
• Failed to update Payload packages

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/9354bfeb896f2fc9. Report an issue: GitHub.