What causes "no matching versions found" in badges/shields?

Widen or correct the version filter/range so it can match existing versions of the artifact.

badges/shields · error · NotFound

no matching versions found

Error message

no matching versions found

What it means

Thrown as NotFound when strategy 'highestVersion' found versions in the metadata, but the user-supplied filter excluded every one of them, leaving the filtered list empty. This is not a server/metadata problem — it means the version list is fine but no version matches the requested filter (e.g. a version range or regex).

Source

Thrown at services/maven-metadata/maven-metadata.service.js:119

          prettyMessage: "property 'release' not found",
        })
      }
      return data.metadata.versioning.release
    } else if (strategy === 'highestVersion') {
      if (
        data.metadata.versioning.versions?.version === undefined ||
        data.metadata.versioning.versions?.version?.length === 0
      ) {
        throw new InvalidResponse({
          prettyMessage: 'no versions found',
        })
      }
      const versions = this.applyFilter({
        versions: data.metadata.versioning.versions.version,
        filter,
      })
      if (versions.length === 0) {
        throw new NotFound({ prettyMessage: 'no matching versions found' })
      }
      return versions.sort(compare).reverse()[0]
    }
    throw new InvalidParameter({ prettyMessage: 'unknown strategy' })
  }

  async handle(
    _namedParams,
    { metadataUrl, versionPrefix, versionSuffix, strategy, filter },
  ) {
    if (
      (versionPrefix !== undefined ||
        versionSuffix !== undefined ||
        filter !== undefined) &&
      strategy !== 'highestVersion'
    ) {
      throw new InvalidParameter({
        prettyMessage: `filter is not valid with strategy ${strategy}`,

View on GitHub (pinned to 766fd8bc89)

Solutions

Widen or correct the version filter/range so it can match existing versions of the artifact.
Log or inspect the unfiltered version list and test the filter against it (this.applyFilter) to see why nothing matches.
Drop the filter entirely to confirm the artifact has resolvable versions, then tighten it incrementally.
Catch the NotFound and return a sensible default or null in your calling code instead of failing.

Example fix

// before
const v = await service.getLatestVersion({ data, strategy: 'highestVersion', filter: '2.0.x' })
// after
const v = await service.getLatestVersion({ data, strategy: 'highestVersion', filter: '2.x' }) // or omit filter

Defensive patterns

Strategy: try-catch

Validate before calling

const filtered = versions.filter(v => matchFilter(v, filter)) // pre-check filter against known versions
if (filtered.length === 0) {
  console.warn(`filter ${filter} matches none of`, versions)
}

Try / catch

try {
  return await service.getLatestVersion({ data, strategy: 'highestVersion', filter })
} catch (err) {
  if (err && err.prettyMessage === 'no matching versions found') {
    return null // or retry with a broader filter
  }
  throw err
}

Prevention

Test version filters/ranges against the artifact's actual version list before finalizing them.
Start with no filter, confirm versions resolve, then tighten the filter.
Avoid hardcoding major-version prefixes that the artifact may have outgrown.
Treat NotFound as an expected outcome (return null/default) rather than an unhandled crash.

When it happens

Trigger: Calling getLatestVersion/handle with a filter (version range/pattern) that matches zero of the versions in data.metadata.versioning.versions.version, e.g. filter '1.2.x' against an artifact that only publishes 2.x versions.

Common situations: Overly restrictive range specifications, typo'd version prefixes, artifacts whose versions jumped major versions, or expecting snapshot/milestone versions that a filter excludes.

Related errors

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