{"record":{"id":"257ddcf73bc3291d","repo":"t8y2/dbx","slug":"unsupported-mongodb-legacy-aggregate-option-key","errorCode":null,"errorMessage":"Unsupported MongoDB Legacy aggregate option: ${key}","messagePattern":"Unsupported MongoDB Legacy aggregate option: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java","lineNumber":641,"sourceCode":"        return iterable;\n    }\n\n    private static void validateAggregateOptions(Document options) {\n        Set<String> supported = Set.of(\n            \"explain\",\n            \"allowDiskUse\",\n            \"cursor\",\n            \"maxTimeMS\",\n            \"maxAwaitTimeMS\",\n            \"bypassDocumentValidation\",\n            \"collation\",\n            \"comment\",\n            \"hint\",\n            \"useCursor\"\n        );\n        for (String key : options.keySet()) {\n            if (!supported.contains(key)) {\n                throw new IllegalArgumentException(\"Unsupported MongoDB Legacy aggregate option: \" + key);\n            }\n        }\n    }\n\n    private static int aggregateMaxRows(JsonObject params) {\n        long value = params.has(\"limit\") ? params.get(\"limit\").getAsLong() : 100;\n        if (value < 0 || value > Integer.MAX_VALUE) {\n            throw new IllegalArgumentException(\"MongoDB aggregate limit must be between 0 and \" + Integer.MAX_VALUE);\n        }\n        return (int) value;\n    }\n\n    private static boolean aggregateBoolean(Document options, String key) {\n        Object value = options.get(key);\n        if (!(value instanceof Boolean)) {\n            throw new IllegalArgumentException(\"MongoDB aggregate option \" + key + \" must be a boolean\");\n        }\n        return (Boolean) value;","sourceCodeStart":623,"sourceCodeEnd":659,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L623-L659","documentation":"validateAggregateOptions enforces a whitelist of supported aggregate options (allowDiskUse, bypassDocumentValidation, collation, comment, hint, useCursor, explain, cursor, etc.). Any top-level options key outside the supported set throws IllegalArgumentException so unsupported options are never silently ignored.","triggerScenarios":"Calling aggregate with options containing a misspelled or unsupported key, e.g. {\"allowDisUse\":true}, {\"maxTimeMS\":5000}, or {\"let\":{...}} on a version of the agent whose whitelist lacks it.","commonSituations":"Typo'd option names; options copied from the MongoDB server aggregate command spec that this agent wrapper does not map; config files grown over time that carry options valid for other drivers/versions.","solutions":["Remove or correct the offending key — check spelling against the supported list in validateAggregateOptions.","Move functionality to a supported option (e.g. use batchSize under cursor, or hint) or drop it.","Update/upgrade the agent to a version that whitelists the option you need.","Validate the options payload client-side against the same whitelist before sending."],"exampleFix":"// before\nDocument options = new Document(\"allowDisUse\", true); // typo\n// after\nDocument options = new Document(\"allowDiskUse\", true);","handlingStrategy":"validation","validationCode":"static final Set<String> SUPPORTED = Set.of(\"explain\",\"cursor\",\"allowDiskUse\",\"bypassDocumentValidation\",\"collation\",\"comment\",\"hint\",\"useCursor\");\nfor (String key : options.keySet()) {\n    if (!SUPPORTED.contains(key)) throw new IllegalArgumentException(\"Unsupported aggregate option: \" + key);\n}","typeGuard":"static boolean allKeysSupported(Document options, Set<String> supported) {\n    return supported.containsAll(options.keySet());\n}","tryCatchPattern":"try {\n    agent.aggregate(db, collection, pipeline, options);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Unsupported MongoDB Legacy aggregate option\")) {\n        String badKey = e.getMessage().substring(e.getMessage().lastIndexOf(':') + 2);\n        options.remove(badKey);\n        // retry with sanitized options, or surface a typed config error\n    } else throw e;\n}","preventionTips":["Mirror the agent's whitelist in your client-side validation","Check option spelling against supported list before sending","On agent upgrades, diff the supported-option set and update configs","Strip unknown options with a sanitizer rather than forwarding blindly"],"tags":["mongodb","aggregate","unsupported-option","whitelist","typo"],"backgroundTag":"unsupported-option","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"}