t8y2/dbx · error · java.lang.IllegalArgumentException

Each update pipeline stage must be an object

Error message

Each update pipeline stage must be an object

What it means

Within an update pipeline array, every element must be a JSON object representing one BSON stage (e.g. {"$set": {...}}). MongoAgent rejects scalar or array elements with this IllegalArgumentException, since the MongoDB Java driver's pipeline overload accepts BSON stage documents, not bare values.

Source

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

        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;
    }

    static boolean isUpdateOperatorDocument(Document doc) {
        if (doc.isEmpty()) {
            return false;
        }
        for (String key : doc.keySet()) {
            if (!key.startsWith("$")) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Wrap each stage in an object: `[{"$set": {...}}, {"$unset": ["oldField"]}]`.
2. Replace bare operator strings like `"$set"` with `{"$set": {"field": value}}`.
3. Validate each element with `element.isJsonObject()` (Gson) before sending.
4. Re-serialize the pipeline from typed objects instead of string concatenation.

Example fix

// before
{"updateOne": {"filter": {"_id": 1}, "update": ["$set", {"a": 1}]}}
// after
{"updateOne": {"filter": {"_id": 1}, "update": [{"$set": {"a": 1}}]}}

// Java (Gson): every stage must be an object
com.google.gson.JsonArray stages = com.google.gson.JsonParser.parseString(updateJson).getAsJsonArray();
for (com.google.gson.JsonElement stage : stages) {
    if (!stage.isJsonObject())
        throw new IllegalArgumentException("Each update pipeline stage must be an object");
}

static boolean isStageObject(com.google.gson.JsonElement e) { return e != null && e.isJsonObject() && e.getAsJsonObject().keySet().stream().allMatch(k -> k.startsWith("$")); }

try { agent.updateOne(filter, updateJson); }
catch (IllegalArgumentException e) {
  if (e.getMessage().contains("pipeline stage must be an object")) {
    // fix the offending stage to {"$op": {...}} and retry
  } else throw e;
}

When it happens

Trigger: Sending `[{"$set": {...}}, "$match"]` or `["$set"]` — a stage written as a bare string instead of `{"$set": ...}`; also arrays nested as stage entries.

Common situations: Converting shell pipelines where quoting is implicit; hand-building pipelines and forgetting the stage-object wrapper; string concatenation bugs that drop `{}` around a stage.

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

• Update pipeline must be an array
• 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/b66a20569cb7c47c. Report an issue: GitHub.