badges/shields · error · NotFound

package not found

Error message

package not found

What it means

The VPM (Unity package manager) version service throws NotFound with message 'package not found' when the fetched VPM registry JSON has no entry for the requested packageId. The registry responded fine, but data.packages[packageId] is undefined.

Source

Thrown at services/vpm/vpm-version.service.js:74

  static defaultBadgeData = {
    label: 'vpm',
  }

  async fetch({ repositoryUrl }) {
    return this._requestJson({
      schema,
      url: repositoryUrl,
    })
  }

  async handle(
    { packageId },
    { repository_url: repositoryUrl, include_prereleases: prereleases },
  ) {
    const data = await this.fetch({ repositoryUrl })
    const pkg = data.packages[packageId]
    if (pkg === undefined)
      throw new NotFound({ prettyMessage: 'package not found' })
    const versions = Object.keys(pkg.versions)
    const version = latest(versions, { pre: prereleases !== undefined })

    return renderVersionBadge({ version })
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Confirm the packageId matches the 'name' field in the package's package.json
  2. Check that repositoryUrl points to the registry actually hosting the package
  3. Search the VPM registry listing for the correct current id
  4. Remove the badge if the package is gone

Example fix

// before
{ packageId: 'com.example.old-name', repositoryUrl: 'https://example.com/vpm.json' }
// after
{ packageId: 'com.example.new-name', repositoryUrl: 'https://example.com/vpm.json' }
Defensive patterns

Strategy: try-catch

Validate before calling

const registry = await fetch(repositoryUrl).then(r => r.json())
if (!(packageId in registry.packages)) throw new Error(`packageId ${packageId} not in registry`);

Type guard

function pkgExists(data, packageId) { return data?.packages != null && Object.prototype.hasOwnProperty.call(data.packages, packageId) }

Try / catch

try {
  const badge = await vpmVersion.handle({ packageId, repositoryUrl })
} catch (e) {
  if (e.message === 'package not found') {
    // fall back to 'vpm | package not found' badge
  } else throw e
}

Prevention

When it happens

Trigger: Querying vpm-version with a packageId not present in the repository's packages list, e.g. a package that moved to another registry or was renamed.

Common situations: Package renamed or republished under a different id, wrong repositoryUrl that hosts a different set of packages, third-party registry no longer listing the package.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of badges/shields@766fd8bc89 (2026-08-30). Data as JSON: /api/errors/856de67e8d71d975. Report an issue: GitHub.