t8y2/dbx · error · java.lang.IllegalArgumentException

Update pipeline must be an array

Error message

Update pipeline must be an array

What it means

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.

Source

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

            filters.add((Document) filter);
        }
        return result.arrayFilters(filters);
    }

    static Document documentForWrite(String docJson) {
        Document doc = Document.parse(docJson);
        convertMongoShellDates(doc);
        return doc;
    }

    private static boolean isUpdatePipelineJson(String updateJson) {
        return updateJson.trim().startsWith("[");
    }

    static List<Document> updatePipelineForWrite(String updateJson) {
        JsonElement parsed = JsonParser.parseString(updateJson);
        if (!parsed.isJsonArray()) {
            throw new IllegalArgumentException("Update pipeline must be an array");
        }
        JsonArray stages = parsed.getAsJsonArray();
        List<Document> pipeline = new ArrayList<>(stages.size());
        for (JsonElement stage : stages) {
            if (!stage.isJsonObject()) {
                // The Java driver pipeline overload accepts BSON stages, not scalar array entries.
                throw new IllegalArgumentException("Each update pipeline stage must be an object");
            }
            pipeline.add(documentForWrite(stage.toString()));
        }
        return pipeline;
    }

    private static Document replacementDocument(Document doc) {
        Document replacement = new Document(doc);
        replacement.remove("_id");
        return replacement;
    }

View on GitHub (pinned to c0390bff16)

Solutions

1. Express the pipeline as a JSON array of stage objects: `[{"$set": {"total": {"$add": ["$price", "$tax"]}}}]`.
2. If you only need operator syntax, pass the object document `{"$set": {...}}` instead of forcing the pipeline path.
3. Check that the serialized `update` value actually begins with `[` after trimming.
4. Log the exact updateJson string being sent to confirm it is an array literal.

Example fix

// before
{"updateMany": {"filter": {}, "update": {"$set": {"ts": "$$NOW"}}}}
// after (pipeline form)
{"updateMany": {"filter": {}, "update": [{"$set": {"ts": "$$NOW"}}]}}

// Java: pipeline updates must be a JSON array
String updateJson = gson.toJson(update);
if (!updateJson.trim().startsWith("[")) {
    throw new IllegalArgumentException("Pipeline update must serialize as a JSON array");
}

static boolean isUpdatePipeline(com.google.gson.JsonElement parsed) { return parsed != null && parsed.isJsonArray(); }

try { agent.updateMany(filter, updateJson); }
catch (IllegalArgumentException e) {
  if (e.getMessage().equals("Update pipeline must be an array")) {
    // wrap operator document in a single-stage array and retry
  } else throw e;
}

When it happens

Trigger: 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.

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

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 update pipeline stage must be an object
• offsets must be an array
• MongoDB aggregate option ${key} must be a non-negative integ
• MongoDB explain verbosity must be queryPlanner, executionSta
• Unsupported findOne option: ${key}

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