badges/shields · error · InvalidParameter

unknown strategy

Error message

unknown strategy

What it means

This InvalidParameter is thrown by the Maven metadata service's getLatestVersion when the requested version-selection `strategy` does not match any implemented strategy. The function only reaches the throw after strategy-specific branches have been exhausted, so it is the catch-all for unrecognized strategy values. Shields.io validates query parameters early, so this surfaces immediately as a user-input error badge rather than a network failure.

Source

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

    } 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}`,
      })
    }

    if (versionPrefix !== undefined || versionSuffix !== undefined) {

View on GitHub (pinned to 766fd8bc89)

Solutions

1. Check the service docs for the exact list of supported `strategy` values and use one verbatim
2. If you only need the newest version, omit `strategy` entirely so the default branch applies
3. Fix typos/casing in the strategy query parameter (values are matched exactly)
4. If you control the code, extend getLatestVersion to accept the strategy you need instead of inventing a value

Example fix

// before
/maven-metadata/v/com.example/artifact.svg?strategy=highest
// after
/maven-metadata/v/com.example/artifact.svg?strategy=highestVersion

const VALID_STRATEGIES = ['highestVersion'] // per service docs
if (strategy !== undefined && !VALID_STRATEGIES.includes(strategy)) {
  throw new Error(`unknown strategy: ${strategy}; valid: ${VALID_STRATEGIES.join(', ')}`)
}

function isKnownStrategy(s) {
  return typeof s === 'string' && ['highestVersion'].includes(s)
}

try {
  await getBadge({ strategy })
} catch (e) {
  if (e instanceof InvalidParameter && /unknown strategy/.test(e.message)) {
    console.error(`Bad strategy '${strategy}', falling back to default`)
    return getBadge({})
  }
  throw e
}

When it happens

Trigger: Passing a `strategy` query parameter whose value is not one of the supported maven-metadata strategies (e.g. `strategy=semver` or a typo like `strategy=highest` when the service expects `highestVersion`/`latest-release` style values). Any badge URL where the strategy branch in getLatestVersion falls through without matching.

Common situations: Copy-pasting badge URLs between services with different strategy names; typos in query strings; documentation drift after strategy options were renamed; URL generators emitting stale strategy values.

Related errors

• filter is not valid with strategy ${strategy}
• strict ssl is required
• invalid url parameter
• requested origin not authorized
• recent downloads not supported for specific versions

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