t8y2/dbx · error · IllegalArgumentException

Unsupported collation option: ${key}

Error message

Unsupported collation option: ${key}

What it means

Collation documents are validated against a fixed whitelist of keys (locale, strength, caseLevel, caseFirst, numericOrdering, alternate, maxVariable, normalization, backwards). Any unrecognized key throws this error before a Collation is built.

Source

Thrown at agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java:816

        List<JsonObject> documents = new ArrayList<>();
        for (Document document : iterable) {
            documents.add(bsonToExtendedJson(document));
        }
        return documentQueryResult(documents, total);
    }

    static Collation collationOrNull(Document document) {
        if (document == null) {
            return null;
        }
        Set<String> supported = Set.of(
            "locale", "strength", "caseLevel", "caseFirst", "numericOrdering",
            "alternate", "maxVariable", "normalization", "backwards"
        );
        for (String key : document.keySet()) {
            if (!supported.contains(key)) {
                throw new IllegalArgumentException("Unsupported collation option: " + key);
            }
        }
        String locale = document.getString("locale");
        if (locale == null || locale.isBlank()) {
            throw new IllegalArgumentException("Invalid collation: locale must not be empty");
        }

        Collation.Builder builder = Collation.builder().locale(locale);
        if (document.containsKey("strength")) {
            Object strength = document.get("strength");
            if (!(strength instanceof Number number) || number.doubleValue() != Math.rint(number.doubleValue())) {
                throw new IllegalArgumentException("Invalid collation option strength: expected an integer from 1 to 5");
            }
            int strengthValue = number.intValue();
            if (strengthValue < 1 || strengthValue > 5) {
                throw new IllegalArgumentException("Invalid collation option strength: expected an integer from 1 to 5");
            }
            builder.collationStrength(CollationStrength.fromInt(strengthValue));

View on GitHub (pinned to c0390bff16)

Solutions

1. Use only supported keys: locale, strength, caseLevel, caseFirst, numericOrdering, alternate, maxVariable, normalization, backwards
2. Fix the key spelling (e.g. 'local' -> 'locale')
3. Remove unknown keys from the collation document
4. Validate/strip the collation object against the whitelist before calling

Example fix

// before
{"collation":{"local":"en_US"}}
// after
{"collation":{"locale":"en_US"}}

const COLLATION_KEYS = new Set(['locale','strength','caseLevel','caseFirst','numericOrdering','alternate','maxVariable','normalization','backwards']);
for (const k of Object.keys(collation || {})) {
  if (!COLLATION_KEYS.has(k)) throw new Error('unsupported collation key: ' + k);
}

function isValidCollationKey(k) {
  return ['locale','strength','caseLevel','caseFirst','numericOrdering','alternate','maxVariable','normalization','backwards'].includes(k);
}

try {
  result = agent.findOne(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith('Unsupported collation option')) {
    const bad = e.getMessage().split(': ').pop();
    delete params.collation[bad];
    result = agent.findOne(params);
  } else throw e;
}

When it happens

Trigger: Passing a collation document with misspelled or extra keys, e.g. {"local":"en"} (typo), {"lang":"en"}, or proprietary keys like {"version":"57.1"}.

Common situations: Typos in key names; copying ICU collation JSON that includes extra metadata; hand-writing collation configs without checking the supported set; forwarding user-supplied collation objects.

Related errors

• Unsupported findOne option: ${key}
• Invalid collation: locale must not be empty
• Invalid collation option strength: expected an integer from
• Invalid collation option ${key}: expected a string
• Unsupported MongoDB aggregate cursor option: ${key}

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/c2bd196285140273. Report an issue: GitHub.