badges/shields · error · InvalidParameter

filter is not valid with strategy

Error message

filter is not valid with strategy ${strategy}

What it means

This InvalidParameter is thrown by the maven-metadata service's handle() when `versionPrefix`, `versionSuffix`, or `filter` are supplied while `strategy` is anything other than 'highestVersion'. Filtering by prefix/suffix only makes sense for the highestVersion strategy, so the combination is rejected up front. The message includes the offending strategy so you can see which value conflicted.

Solutions

1. Change `strategy` to `highestVersion` when using versionPrefix/versionSuffix/filter
2. Remove versionPrefix/versionSuffix/filter if you want to keep the current strategy
3. Use only `filter` (glob) with highestVersion instead of prefix+suffix
4. Update your badge generator so it emits filter params only for highestVersion

Example fix

// before
?strategy=latest-release&versionPrefix=2.
// after
?strategy=highestVersion&versionPrefix=2.

const wantsFilter = versionPrefix !== undefined || versionSuffix !== undefined || filter !== undefined
if (wantsFilter && strategy !== 'highestVersion') {
  throw new Error('versionPrefix/versionSuffix/filter require strategy=highestVersion')
}

function canUseFilter(params) {
  const hasFilter = params.versionPrefix !== undefined || params.versionSuffix !== undefined || params.filter !== undefined
  return !hasFilter || params.strategy === 'highestVersion'
}

try {
  return await renderBadge(params)
} catch (e) {
  if (e instanceof InvalidParameter && /filter is not valid with strategy/.test(e.message)) {
    return renderBadge({ ...params, strategy: 'highestVersion' })
  }
  throw e
}

When it happens

Trigger: A badge URL combining e.g. `?strategy=latest-release&versionPrefix=1.` or `?strategy=semver&filter=.*-beta` — any of versionPrefix/versionSuffix/filter present with strategy !== 'highestVersion'.

Common situations: Users adding a version filter to an existing badge URL without changing the strategy; badge generators that emit both parameters; migrating from defaults to an explicit strategy and keeping old filter params.

Related errors

• unknown strategy
• artifact or version not found
• directory not found
• domain is blocked
• extension is applicable for type file only

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

Appendix: source

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

      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) {
      filter = `${versionPrefix || ''}*${versionSuffix || ''}`
    }

    const data = await this.fetch({ metadataUrl })
    return renderVersionBadge({
      version: this.constructor.getLatestVersion({ data, strategy, filter }),
    })
  }
}

View on GitHub (pinned to 766fd8bc89)