{"record":{"id":"0a12570edfd08985","repo":"t8y2/dbx","slug":"unsupported-findone-option-key","errorCode":null,"errorMessage":"Unsupported findOne option: ${key}","messagePattern":"Unsupported findOne option: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java","lineNumber":735,"sourceCode":"            throw new IllegalArgumentException(\n                \"MongoDB explain verbosity must be queryPlanner, executionStats, or allPlansExecution\");\n        }\n        return verbosity;\n    }\n\n    private static Object findOne(JsonObject params) {\n        MongoClient c = requireClient();\n        String database = params.get(\"database\").getAsString();\n        String collection = params.get(\"collection\").getAsString();\n        Document filter = documentOrNull(params, \"filter\");\n        Document projection = documentOrNull(params, \"projection\");\n        Document options = documentOrNull(params, \"options\");\n        Document sort = null;\n\n        if (options != null) {\n            for (String key : options.keySet()) {\n                if (!\"sort\".equals(key)) {\n                    throw new IllegalArgumentException(\"Unsupported findOne option: \" + key);\n                }\n            }\n            Object rawSort = options.get(\"sort\");\n            if (rawSort != null) {\n                if (!(rawSort instanceof Document sortDocument)) {\n                    throw new IllegalArgumentException(\"Invalid findOne option sort: expected an object\");\n                }\n                sort = sortDocument;\n            }\n        }\n\n        var iterable = c.getDatabase(database).getCollection(collection).find(filter == null ? new Document() : filter);\n        if (projection != null) {\n            iterable = iterable.projection(projection);\n        }\n        if (sort != null) {\n            iterable = iterable.sort(sort);\n        }","sourceCodeStart":717,"sourceCodeEnd":753,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L717-L753","documentation":"Thrown by MongoAgent.findOne when the options document contains a key not in the supported findOne option set (filter/projection-style options). This is a strict allow-list guard: any unrecognized option key is rejected rather than silently ignored, to prevent options that would silently not apply.","triggerScenarios":"Calling findOne with options such as {\"limit\":1}, {\"projection\":{...}}, {\"maxTimeMS\":...}, or any key other than \"sort\".","commonSituations":"Copying option objects from find() calls (which support many options) into findOne; assuming findOne supports limit/projection; forwarding raw client-supplied option objects.","solutions":["Remove any options other than \"sort\" from the findOne options","Move unsupported options (e.g. projection) into the appropriate parameters of the API, if available","Apply limit 1 client-side after fetching, or use find with limit instead of findOne","Whitelist/strip keys before passing options"],"exampleFix":"// before\n{\"collection\":\"users\",\"filter\":{},\"options\":{\"sort\":{\"age\":1},\"limit\":1}}\n// after\n{\"collection\":\"users\",\"filter\":{},\"options\":{\"sort\":{\"age\":1}}}","handlingStrategy":"validation","validationCode":"const ALLOWED = ['sort'];\nfor (const k of Object.keys(opts || {})) {\n  if (!ALLOWED.includes(k)) throw new Error('findOne does not support option: ' + k);\n}","typeGuard":"function hasOnlySupportedFindOneOptions(opts) {\n  return opts == null || Object.keys(opts).every(k => k === 'sort');\n}","tryCatchPattern":"try {\n  result = agent.findOne(params);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Unsupported findOne option\")) {\n    params.options = { sort: params.options?.sort };\n    result = agent.findOne(params);\n  } else throw e;\n}","preventionTips":["Only pass { sort: ... } in findOne options","Do not reuse find() option objects for findOne","Strip/whitelist keys before forwarding client options","Use find(...).limit(1) when you need projection/limit etc."],"tags":["mongodb","findone","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"}