{"record":{"id":"c2bd196285140273","repo":"t8y2/dbx","slug":"unsupported-collation-option-key","errorCode":null,"errorMessage":"Unsupported collation option: ${key}","messagePattern":"Unsupported collation option: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java","lineNumber":816,"sourceCode":"\n        List<JsonObject> documents = new ArrayList<>();\n        for (Document document : iterable) {\n            documents.add(bsonToExtendedJson(document));\n        }\n        return documentQueryResult(documents, total);\n    }\n\n    static Collation collationOrNull(Document document) {\n        if (document == null) {\n            return null;\n        }\n        Set<String> supported = Set.of(\n            \"locale\", \"strength\", \"caseLevel\", \"caseFirst\", \"numericOrdering\",\n            \"alternate\", \"maxVariable\", \"normalization\", \"backwards\"\n        );\n        for (String key : document.keySet()) {\n            if (!supported.contains(key)) {\n                throw new IllegalArgumentException(\"Unsupported collation option: \" + key);\n            }\n        }\n        String locale = document.getString(\"locale\");\n        if (locale == null || locale.isBlank()) {\n            throw new IllegalArgumentException(\"Invalid collation: locale must not be empty\");\n        }\n\n        Collation.Builder builder = Collation.builder().locale(locale);\n        if (document.containsKey(\"strength\")) {\n            Object strength = document.get(\"strength\");\n            if (!(strength instanceof Number number) || number.doubleValue() != Math.rint(number.doubleValue())) {\n                throw new IllegalArgumentException(\"Invalid collation option strength: expected an integer from 1 to 5\");\n            }\n            int strengthValue = number.intValue();\n            if (strengthValue < 1 || strengthValue > 5) {\n                throw new IllegalArgumentException(\"Invalid collation option strength: expected an integer from 1 to 5\");\n            }\n            builder.collationStrength(CollationStrength.fromInt(strengthValue));","sourceCodeStart":798,"sourceCodeEnd":834,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L798-L834","documentation":"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.","triggerScenarios":"Passing a collation document with misspelled or extra keys, e.g. {\"local\":\"en\"} (typo), {\"lang\":\"en\"}, or proprietary keys like {\"version\":\"57.1\"}.","commonSituations":"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.","solutions":["Use only supported keys: locale, strength, caseLevel, caseFirst, numericOrdering, alternate, maxVariable, normalization, backwards","Fix the key spelling (e.g. 'local' -> 'locale')","Remove unknown keys from the collation document","Validate/strip the collation object against the whitelist before calling"],"exampleFix":"// before\n{\"collation\":{\"local\":\"en_US\"}}\n// after\n{\"collation\":{\"locale\":\"en_US\"}}","handlingStrategy":"validation","validationCode":"const COLLATION_KEYS = new Set(['locale','strength','caseLevel','caseFirst','numericOrdering','alternate','maxVariable','normalization','backwards']);\nfor (const k of Object.keys(collation || {})) {\n  if (!COLLATION_KEYS.has(k)) throw new Error('unsupported collation key: ' + k);\n}","typeGuard":"function isValidCollationKey(k) {\n  return ['locale','strength','caseLevel','caseFirst','numericOrdering','alternate','maxVariable','normalization','backwards'].includes(k);\n}","tryCatchPattern":"try {\n  result = agent.findOne(params);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith('Unsupported collation option')) {\n    const bad = e.getMessage().split(': ').pop();\n    delete params.collation[bad];\n    result = agent.findOne(params);\n  } else throw e;\n}","preventionTips":["Keep a copy of the supported collation key whitelist handy","Watch for the locale/local typo","Strip ICU metadata keys before sending collation","Validate collation objects from clients against the whitelist"],"tags":["mongodb","collation","validation","unsupported-option"],"backgroundTag":"unsupported-option-key","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}