What causes "filter is not valid with strategy ${strategy}" in badges/shields?

Change `strategy` to `highestVersion` when using versionPrefix/versionSuffix/filter

badges/shields · error · InvalidParameter

filter is not valid with strategy ${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.

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)

Solutions

Change `strategy` to `highestVersion` when using versionPrefix/versionSuffix/filter
Remove versionPrefix/versionSuffix/filter if you want to keep the current strategy
Use only `filter` (glob) with highestVersion instead of prefix+suffix
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.

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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
}

Prevention

Encode the strategy/filter compatibility rule in your URL-builder so invalid combos are unrepresentable
When adding versionPrefix/versionSuffix, always set strategy=highestVersion in the same change
Prefer a single `filter` glob over prefix+suffix to reduce parameter surface
Add an integration test per strategy/filter combination you rely on

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

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