{"record":{"id":"6052f1ac4d51e359","repo":"t8y2/dbx","slug":"update-pipeline-must-be-an-array","errorCode":null,"errorMessage":"Update pipeline must be an array","messagePattern":"Update pipeline must be an array","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java","lineNumber":1646,"sourceCode":"            filters.add((Document) filter);\n        }\n        return result.arrayFilters(filters);\n    }\n\n    static Document documentForWrite(String docJson) {\n        Document doc = Document.parse(docJson);\n        convertMongoShellDates(doc);\n        return doc;\n    }\n\n    private static boolean isUpdatePipelineJson(String updateJson) {\n        return updateJson.trim().startsWith(\"[\");\n    }\n\n    static List<Document> updatePipelineForWrite(String updateJson) {\n        JsonElement parsed = JsonParser.parseString(updateJson);\n        if (!parsed.isJsonArray()) {\n            throw new IllegalArgumentException(\"Update pipeline must be an array\");\n        }\n        JsonArray stages = parsed.getAsJsonArray();\n        List<Document> pipeline = new ArrayList<>(stages.size());\n        for (JsonElement stage : stages) {\n            if (!stage.isJsonObject()) {\n                // The Java driver pipeline overload accepts BSON stages, not scalar array entries.\n                throw new IllegalArgumentException(\"Each update pipeline stage must be an object\");\n            }\n            pipeline.add(documentForWrite(stage.toString()));\n        }\n        return pipeline;\n    }\n\n    private static Document replacementDocument(Document doc) {\n        Document replacement = new Document(doc);\n        replacement.remove(\"_id\");\n        return replacement;\n    }","sourceCodeStart":1628,"sourceCodeEnd":1664,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L1628-L1664","documentation":"When the `update` parameter for updateOne/updateMany is a pipeline-style update, MongoAgent parses it with Gson and requires a JSON array of pipeline stages. If the JSON parses but is not an array (an object or scalar), updatePipelineForWrite throws this IllegalArgumentException because the driver's pipeline overload only accepts List<Document> stages.","triggerScenarios":"Sending an update that starts with `[` only in intent but actually serializes as an object, e.g. `{\"$set\": {\"a\": 1}}` reaching updatePipelineForWrite via a path that treats it as a pipeline, or passing a bare scalar/string as update.","commonSituations":"Mixing operator-document updates with pipeline updates; a code path deciding pipeline-vs-document via `updateJson.trim().startsWith(\"[\")` when the payload was re-serialized or trimmed differently; tools that unwrap arrays into objects.","solutions":["Express the pipeline as a JSON array of stage objects: `[{\"$set\": {\"total\": {\"$add\": [\"$price\", \"$tax\"]}}}]`.","If you only need operator syntax, pass the object document `{\"$set\": {...}}` instead of forcing the pipeline path.","Check that the serialized `update` value actually begins with `[` after trimming.","Log the exact updateJson string being sent to confirm it is an array literal."],"exampleFix":"// before\n{\"updateMany\": {\"filter\": {}, \"update\": {\"$set\": {\"ts\": \"$$NOW\"}}}}\n// after (pipeline form)\n{\"updateMany\": {\"filter\": {}, \"update\": [{\"$set\": {\"ts\": \"$$NOW\"}}]}}","handlingStrategy":"validation","validationCode":"// Java: pipeline updates must be a JSON array\nString updateJson = gson.toJson(update);\nif (!updateJson.trim().startsWith(\"[\")) {\n    throw new IllegalArgumentException(\"Pipeline update must serialize as a JSON array\");\n}","typeGuard":"static boolean isUpdatePipeline(com.google.gson.JsonElement parsed) { return parsed != null && parsed.isJsonArray(); }","tryCatchPattern":"try { agent.updateMany(filter, updateJson); }\ncatch (IllegalArgumentException e) {\n  if (e.getMessage().equals(\"Update pipeline must be an array\")) {\n    // wrap operator document in a single-stage array and retry\n  } else throw e;\n}","preventionTips":["Use aggregation-pipeline update syntax only when you need $-stage features like $$NOW","Keep pipeline construction typed (List<Map<String,Object>>) instead of string concat","Log updateJson before dispatch to verify it starts with '['"],"tags":["mongodb","validation","update-pipeline","json"],"backgroundTag":"invalid-argument-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"}