{"record":{"id":"13881d0025e89e5a","repo":"t8y2/dbx","slug":"invalid-collation-option-key-expected-a-string","errorCode":null,"errorMessage":"Invalid collation option ${key}: expected a string","messagePattern":"Invalid collation option (.+?): expected a string","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java","lineNumber":873,"sourceCode":"            builder.backwards(collationBoolean(document, \"backwards\"));\n        }\n        return builder.build();\n    }\n\n    private static boolean collationBoolean(Document document, String key) {\n        Object value = document.get(key);\n        if (value instanceof Boolean booleanValue) {\n            return booleanValue;\n        }\n        throw new IllegalArgumentException(\"Invalid collation option \" + key + \": expected a boolean\");\n    }\n\n    private static String collationString(Document document, String key) {\n        Object value = document.get(key);\n        if (value instanceof String stringValue) {\n            return stringValue;\n        }\n        throw new IllegalArgumentException(\"Invalid collation option \" + key + \": expected a string\");\n    }\n\n    static CollectionTotal collectionTotal(MongoCollection<Document> collection, Document filter) {\n        return collectionTotal(collection, filter, null);\n    }\n\n    static CollectionTotal collectionTotal(MongoCollection<Document> collection, Document filter, Collation collation) {\n        if (filter.isEmpty()) {\n            return new CollectionTotal(collection.estimatedDocumentCount(), false);\n        }\n        CountOptions options = new CountOptions();\n        if (collation != null) {\n            options.collation(collation);\n        }\n        return new CollectionTotal(collection.countDocuments(filter, options), true);\n    }\n\n    static Map<String, Object> documentQueryResult(List<?> documents, CollectionTotal total) {","sourceCodeStart":855,"sourceCodeEnd":891,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L855-L891","documentation":"MongoAgent.collationString reads a collation option (e.g. locale, strength) from the request document and requires it to be a String, because the MongoDB collation document maps option names to string values. When a caller supplies a collation option whose value is not a JSON string (e.g. a number or object), the driver throws IllegalArgumentException before any query runs. It is a client-side input validation error protecting the server from a malformed collation document.","triggerScenarios":"Calling a query/aggregate/count operation with a collation document where an option value is a non-string JSON type, e.g. {\"collation\": {\"strength\": 2}} or {\"caseLevel\": true} passed through the collation options document.","commonSituations":"Copying a collation example where strength or numericOrdering are given as numbers; hand-writing collation JSON where booleans/ints slip in; older code that predates correct collation typing.","solutions":["Find the collation option named in the message and change its value to a string (e.g. \"strength\": \"2\", \"caseLevel\": \"true\" depending on the agent's expected schema).","Check which API call you made and how its collation document is built; ensure all values passed under collation keys are JSON strings.","If you don't need case/diacritic-sensitive comparison, drop the collation option entirely so the default collation is used."],"exampleFix":"// before\n{\"find\": \"users\", \"filter\": {}, \"collation\": {\"locale\": \"en\", \"strength\": 2}}\n// after\n{\"find\": \"users\", \"filter\": {}, \"collation\": {\"locale\": \"en\", \"strength\": \"2\"}}","handlingStrategy":"validation","validationCode":"// JS caller\nfunction validateCollation(collation) {\n  if (collation == null) return true;\n  return Object.entries(collation).every(([k, v]) => typeof v === \"string\");\n}\n// e.g. fix: collation.strength = String(collation.strength);","typeGuard":"function isStringCollation(c) {\n  return c == null || Object.values(c).every(v => typeof v === \"string\");\n}","tryCatchPattern":"try {\n  await agent.find({ database, collection, filter, collation });\n} catch (e) {\n  if (String(e.message).includes(\"Invalid collation option\")) {\n    // coerce offending option to string and retry once\n  } else throw e;\n}","preventionTips":["Quote all collation option values when building the document.","Keep a single collation constant/helper instead of ad-hoc objects.","Validate the collation object against the option schema before each query."],"tags":["mongodb","validation","collation","type-mismatch"],"backgroundTag":"invalid-parameter-type","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"}