{"record":{"id":"b1e03758d88d83d3","repo":"t8y2/dbx","slug":"mongodb-insertmany-documents-must-be-a-json-array","errorCode":null,"errorMessage":"MongoDB insertMany documents must be a JSON array","messagePattern":"MongoDB insertMany documents must be a JSON 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":1474,"sourceCode":"    }\n\n    private static Object insertDocument(JsonObject params) {\n        MongoClient c = requireClient();\n        String database = params.get(\"database\").getAsString();\n        String collection = params.get(\"collection\").getAsString();\n        String docJson = params.get(\"doc_json\").getAsString();\n\n        Document doc = Document.parse(docJson);\n        c.getDatabase(database).getCollection(collection).insertOne(doc);\n        Object insertedId = convertValue(doc.get(\"_id\"));\n        return Collections.singletonMap(\"inserted_id\", insertedId);\n    }\n\n    private static Object insertDocuments(JsonObject params) {\n        String docsJson = params.get(\"docs_json\").getAsString();\n        JsonElement parsed = JsonParser.parseString(docsJson);\n        if (!parsed.isJsonArray()) {\n            throw new IllegalArgumentException(\"MongoDB insertMany documents must be a JSON array\");\n        }\n\n        List<Document> documents = new ArrayList<>();\n        for (JsonElement item : parsed.getAsJsonArray()) {\n            if (!item.isJsonObject()) {\n                throw new IllegalArgumentException(\"Each MongoDB insertMany document must be an object\");\n            }\n            documents.add(documentForWrite(item.toString()));\n        }\n        if (documents.isEmpty()) {\n            return Collections.singletonMap(\"affected_rows\", 0);\n        }\n\n        MongoClient client = requireClient();\n        String database = params.get(\"database\").getAsString();\n        String collection = params.get(\"collection\").getAsString();\n        client.getDatabase(database).getCollection(collection).insertMany(documents);\n        return Collections.singletonMap(\"affected_rows\", documents.size());","sourceCodeStart":1456,"sourceCodeEnd":1492,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java#L1456-L1492","documentation":"The insertDocuments path (insertMany) parses the 'docs_json' parameter and requires it to be a JSON array of documents. This error means the parsed value was not an array — typically a single JSON object was passed for an operation that always inserts a batch.","triggerScenarios":"Calling insertMany/insertDocuments with docs_json set to '{\"name\":\"a\"}' instead of '[{\"name\":\"a\"}]'; passing a string, number, or other non-array JSON value.","commonSituations":"Developers inserting one document and forgetting to wrap it in an array; code migrated from insertOne semantics to insertMany without changing the payload; templates that serialize a single dict/map into the parameter.","solutions":["Wrap the document in a JSON array: [{ ...doc... }]","If a single insert is intended, use the insertOne-style operation instead","Ensure the serializer emits a top-level array (e.g. collect documents into a list before serializing)"],"exampleFix":"// before\nagent.insertMany(coll, \"{\\\"name\\\": \\\"alice\\\"}\");\n// after\nagent.insertMany(coll, \"[{\\\"name\\\": \\\"alice\\\"}]\");","handlingStrategy":"validation","validationCode":"const parsed = JSON.parse(docsJson);\nif (!Array.isArray(parsed)) {\n  docsJson = JSON.stringify([parsed]); // wrap single object into an array\n}","typeGuard":"const isDocumentArray = (v) =>\n  Array.isArray(v) && v.length > 0 && v.every(d => d !== null && typeof d === 'object' && !Array.isArray(d));","tryCatchPattern":"try {\n  agent.insertMany(coll, docsJson);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().includes(\"must be a JSON array\")) {\n    agent.insertMany(coll, JSON.stringify([JSON.parse(docsJson)]));\n  } else throw e;\n}","preventionTips":["Always wrap single documents in an array for insertMany","Use insertOne for single-document inserts","Centralize doc serialization in one helper that guarantees an array"],"tags":["mongodb","insertmany","argument-validation"],"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"}