{"record":{"id":"33148dd172125ace","repo":"t8y2/dbx","slug":"unsupported-update-option-key","errorCode":null,"errorMessage":"Unsupported update option: <key>","messagePattern":"Unsupported update option: <key>","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java","lineNumber":1613,"sourceCode":"        requireBulkUpdateOperatorDocument(update);\n        return many ? col.updateMany(filter, update, options) : col.updateOne(filter, update, options);\n    }\n\n    private static UpdateResult updateDocumentsWithPipeline(\n        MongoCollection<Document> col, Document filter, List<Document> pipeline,\n        UpdateOptions options, boolean many) {\n        return many ? col.updateMany(filter, pipeline, options) : col.updateOne(filter, pipeline, options);\n    }\n\n    static UpdateOptions updateOptionsForWrite(String optionsJson) {\n        UpdateOptions result = new UpdateOptions();\n        if (optionsJson == null || optionsJson.trim().isEmpty()) {\n            return result;\n        }\n        Document options = Document.parse(optionsJson);\n        for (String key : options.keySet()) {\n            if (!\"arrayFilters\".equals(key)) {\n                throw new IllegalArgumentException(\"Unsupported update option: \" + key);\n            }\n        }\n        Object rawFilters = options.get(\"arrayFilters\");\n        if (rawFilters == null) {\n            return result;\n        }\n        if (!(rawFilters instanceof List<?>)) {\n            throw new IllegalArgumentException(\"arrayFilters must be an array\");\n        }\n        List<Document> filters = new ArrayList<>();\n        for (Object filter : (List<?>) rawFilters) {\n            if (!(filter instanceof Document)) {\n                throw new IllegalArgumentException(\"Each arrayFilters entry must be an object\");\n            }\n            filters.add((Document) filter);\n        }\n        return result.arrayFilters(filters);\n    }","sourceCodeStart":1595,"sourceCodeEnd":1631,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L1595-L1631","documentation":"The update-options parser only permits the 'arrayFilters' option. Any other key in the options_json document triggers this error, failing fast so callers know the option was silently ignored (the underlying API surface intentionally whitelists options).","triggerScenarios":"Passing options like {\"upsert\": true}, {\"bypassDocumentValidation\": true}, or a typo'd key such as {\"arrayFilter\": [...]} (missing 's') in the update operation's options_json. Any key other than exactly 'arrayFilters' throws.","commonSituations":"Copy-pasting MongoDB driver options (upsert, collation, hint) that this tool does not support; misspelling arrayFilters; building options dynamically from user input containing unsupported flags; version drift where a previously tolerated option was removed from the whitelist.","solutions":["Remove unsupported keys; keep only {\"arrayFilters\": [...]} if array-filtered updates are needed","Fix typos: the key must be exactly \"arrayFilters\"","If you need upsert or other options, apply them via a supported API surface or feature request rather than options_json"],"exampleFix":"// before\noptionsJson = \"{\\\"upsert\\\": true, \\\"arrayFilters\\\": [{\\\"elem.age\\\": {\\\"$gte\\\": 21}}]}\";\n// after\noptionsJson = \"{\\\"arrayFilters\\\": [{\\\"elem.age\\\": {\\\"$gte\\\": 21}}]}\";","handlingStrategy":"validation","validationCode":"const ALLOWED = ['arrayFilters'];\nconst opts = optionsJson ? JSON.parse(optionsJson) : {};\nconst unsupported = Object.keys(opts).filter(k => !ALLOWED.includes(k));\nif (unsupported.length) throw new Error(`Unsupported update options: ${unsupported.join(', ')}`);","typeGuard":"const hasOnlySupportedOptions = (opts) =>\n  opts == null || Object.keys(opts).every(k => k === 'arrayFilters');","tryCatchPattern":"try {\n  agent.update(filter, updateJson, optionsJson);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Unsupported update option:\")) {\n    const badKey = e.getMessage().split(':')[1].trim();\n    const opts = JSON.parse(optionsJson); delete opts[badKey];\n    agent.update(filter, updateJson, JSON.stringify(opts)); // retry without bad option\n  } else throw e;\n}","preventionTips":["Check the supported-options list before passing options_json","Spell \"arrayFilters\" exactly (plural, camelCase)","Do not forward generic MongoDB driver options like upsert through this surface"],"tags":["mongodb","update-options","argument-validation","whitelist"],"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"}