t8y2/dbx · error · java.lang.IllegalArgumentException

MongoDB insertMany documents must be a JSON array

Error message

MongoDB insertMany documents must be a JSON array

What it means

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.

Source

Thrown at agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java:1474

    }

    private static Object insertDocument(JsonObject params) {
        MongoClient c = requireClient();
        String database = params.get("database").getAsString();
        String collection = params.get("collection").getAsString();
        String docJson = params.get("doc_json").getAsString();

        Document doc = Document.parse(docJson);
        c.getDatabase(database).getCollection(collection).insertOne(doc);
        Object insertedId = convertValue(doc.get("_id"));
        return Collections.singletonMap("inserted_id", insertedId);
    }

    private static Object insertDocuments(JsonObject params) {
        String docsJson = params.get("docs_json").getAsString();
        JsonElement parsed = JsonParser.parseString(docsJson);
        if (!parsed.isJsonArray()) {
            throw new IllegalArgumentException("MongoDB insertMany documents must be a JSON array");
        }

        List<Document> documents = new ArrayList<>();
        for (JsonElement item : parsed.getAsJsonArray()) {
            if (!item.isJsonObject()) {
                throw new IllegalArgumentException("Each MongoDB insertMany document must be an object");
            }
            documents.add(documentForWrite(item.toString()));
        }
        if (documents.isEmpty()) {
            return Collections.singletonMap("affected_rows", 0);
        }

        MongoClient client = requireClient();
        String database = params.get("database").getAsString();
        String collection = params.get("collection").getAsString();
        client.getDatabase(database).getCollection(collection).insertMany(documents);
        return Collections.singletonMap("affected_rows", documents.size());

View on GitHub (pinned to c0390bff16)

Solutions

1. Wrap the document in a JSON array: [{ ...doc... }]
2. If a single insert is intended, use the insertOne-style operation instead
3. Ensure the serializer emits a top-level array (e.g. collect documents into a list before serializing)

Example fix

// before
agent.insertMany(coll, "{\"name\": \"alice\"}");
// after
agent.insertMany(coll, "[{\"name\": \"alice\"}]");

const parsed = JSON.parse(docsJson);
if (!Array.isArray(parsed)) {
  docsJson = JSON.stringify([parsed]); // wrap single object into an array
}

const isDocumentArray = (v) =>
  Array.isArray(v) && v.length > 0 && v.every(d => d !== null && typeof d === 'object' && !Array.isArray(d));

try {
  agent.insertMany(coll, docsJson);
} catch (IllegalArgumentException e) {
  if (e.getMessage().includes("must be a JSON array")) {
    agent.insertMany(coll, JSON.stringify([JSON.parse(docsJson)]));
  } else throw e;
}

When it happens

Trigger: Calling insertMany/insertDocuments with docs_json set to '{"name":"a"}' instead of '[{"name":"a"}]'; passing a string, number, or other non-array JSON value.

Common situations: 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.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Each MongoDB insertMany document must be an object
• dropIndex only accepts a string index name or JSON document;
• dropIndexes only accepts arrays of string index names
• dropIndexes only accepts non-empty string arrays
• dropIndex only accepts a string index name or JSON document

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/b1e03758d88d83d3. Report an issue: GitHub.