{"record":{"id":"9354bfeb896f2fc9","repo":"payloadcms/payload","slug":"no-version-or-tag-version-found-for-package","errorCode":null,"errorMessage":"No version or tag \"${version}\" found for package: ${packageName}","messagePattern":"No version or tag \"(.+?)\" found for package: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/create-payload-app/src/utils/resolvePackageVersion.ts","lineNumber":66,"sourceCode":"  }\n  return versionOrTag\n}\n\nasync function fetchDistTags(packageName: string): Promise<Record<string, string>> {\n  const response = await fetch(`https://registry.npmjs.org/-/package/${packageName}/dist-tags`)\n  return (await response.json()) as Record<string, string>\n}\n\nasync function verifyVersionExists({\n  packageName,\n  version,\n}: {\n  packageName: string\n  version: string\n}): Promise<void> {\n  const response = await fetch(`https://registry.npmjs.org/${packageName}/${version}`)\n  if (response.status !== 200) {\n    throw new Error(`No version or tag \"${version}\" found for package: ${packageName}`)\n  }\n}\n","sourceCodeStart":48,"sourceCodeEnd":69,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/create-payload-app/src/utils/resolvePackageVersion.ts#L48-L69","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a known dist-tag: `--payload-version latest` or `--payload-version canary`.","If specifying a concrete version, copy the exact string from https://registry.npmjs.org/payload (no leading 'v').","Check connectivity to https://registry.npmjs.org and any configured registry mirror.","For @payloadcms/* packages, confirm the version exists for that specific package."],"exampleFix":"// before\n$ npx create-payload-app . --payload-version v3.40.0\n\n// after\n$ npx create-payload-app . --payload-version 3.40.0","handlingStrategy":"validation","validationCode":"async function resolveOrFail(pkg: string, tagOrVersion: string) {\n  const tagsRes = await fetch(`https://registry.npmjs.org/-/package/${pkg}/dist-tags`)\n  const tags = await tagsRes.json()\n  if (tags[tagOrVersion]) return tags[tagOrVersion]\n  const verRes = await fetch(`https://registry.npmjs.org/${pkg}/${tagOrVersion}`)\n  if (verRes.status !== 200) {\n    throw new Error(`${pkg}@${tagOrVersion} is neither a dist-tag nor a published version`)\n  }\n  return tagOrVersion\n}","typeGuard":"const DIST_TAGS = ['latest', 'canary', 'next', 'beta'] as const\nfunction isDistTag(x: string): x is (typeof DIST_TAGS)[number] {\n  return (DIST_TAGS as readonly string[]).includes(x)\n}\nfunction isSemver(x: string): boolean {\n  return /^\\d+\\.\\d+\\.\\d+(-[\\w.]+)?$/.test(x)\n}","tryCatchPattern":null,"preventionTips":["Prefer dist-tags (latest, canary) over hardcoded versions.","Copy concrete versions verbatim from the registry, without a leading 'v'.","Verify registry connectivity and any configured mirror."],"tags":["create-payload-app","cli","npm","network","validation"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}