{"record":{"id":"c5ecd446551d1bb6","repo":"t8y2/dbx","slug":"invalid-collation-locale-must-not-be-empty","errorCode":null,"errorMessage":"Invalid collation: locale must not be empty","messagePattern":"Invalid collation: locale must not be empty","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java","lineNumber":821,"sourceCode":"        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));\n        }\n        if (document.containsKey(\"caseLevel\")) {\n            builder.caseLevel(collationBoolean(document, \"caseLevel\"));\n        }\n        if (document.containsKey(\"caseFirst\")) {","sourceCodeStart":803,"sourceCodeEnd":839,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L803-L839","documentation":"Thrown by MongoAgent.collationOrNull while building a MongoDB Collation from the collation document: the 'locale' field was present but empty. Locale is the only mandatory collation field and an empty string is invalid, so the collation (and the query carrying it) is rejected.","triggerScenarios":"Passing collation {} or {\"strength\":2} without locale, or {\"locale\":\"\"} / {\"locale\":\"   \"}.","commonSituations":"Building collation objects conditionally and forgetting locale; templated configs where the locale variable is empty; assuming the driver defaults the locale (it does not).","solutions":["Add a valid locale string, e.g. {\"locale\":\"en\"} or \"simple\" for no collation","Check that the locale variable is populated before constructing the collation","Omit the collation entirely if locale is unknown","Normalize empty strings to null and skip collation"],"exampleFix":"// before\n{\"collation\":{\"locale\":\"\",\"strength\":2}}\n// after\n{\"collation\":{\"locale\":\"en\",\"strength\":2}}","handlingStrategy":"validation","validationCode":"if (!collation || typeof collation.locale !== 'string' || collation.locale.trim() === '') {\n  throw new Error('collation requires a non-empty locale');\n}","typeGuard":"function hasCollationLocale(c) {\n  return typeof c?.locale === 'string' && c.locale.trim().length > 0;\n}","tryCatchPattern":"try {\n  result = agent.findOne(params);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage() === 'Invalid collation: locale must not be empty') {\n    delete params.collation;\n    result = agent.findOne(params);\n  } else throw e;\n}","preventionTips":["Always set locale when building a collation","Check locale config variables are populated before use","Use 'simple' explicitly when no locale-specific rules are needed","Skip collation entirely when locale is unknown"],"tags":["mongodb","collation","validation","missing-field"],"backgroundTag":"missing-required-field","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"}