t8y2/dbx · error · IllegalArgumentException

Each MongoDB aggregate pipeline stage must be an object

Error message

Each MongoDB aggregate pipeline stage must be an object

What it means

Thrown by MongoAgent.aggregatePipeline while iterating the parsed pipeline array when an element is not a JSON object. Every aggregation stage must be a document like {"$match": ...}; a bare string, number, or nested array at stage position triggers this rejection.

Source

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

            documents.subList(maxRows, documents.size()).clear();
            extendedDocuments.subList(maxRows, extendedDocuments.size()).clear();
        }
        return documentQueryResultWithExtended(documents, extendedDocuments, total);
    }

    static List<Document> aggregatePipeline(JsonObject params) {
        String source = stringOrNull(params, "pipeline");
        if (source == null || source.isBlank()) {
            throw new IllegalArgumentException("MongoDB aggregate pipeline is required");
        }
        JsonElement parsed = JsonParser.parseString(source);
        if (!parsed.isJsonArray()) {
            throw new IllegalArgumentException("MongoDB aggregate pipeline must be a JSON array");
        }
        List<Document> pipeline = new ArrayList<>();
        for (JsonElement stage : parsed.getAsJsonArray()) {
            if (!stage.isJsonObject()) {
                throw new IllegalArgumentException("Each MongoDB aggregate pipeline stage must be an object");
            }
            pipeline.add(Document.parse(stage.toString()));
        }
        return pipeline;
    }

    static Document aggregateOptions(JsonObject params) {
        Document options = documentOrNull(params, "options");
        return options == null ? new Document() : options;
    }

    static boolean aggregateExplain(Document options) {
        Object explain = options.get("explain");
        if (explain == null) {
            return false;
        }
        if (!(explain instanceof Boolean)) {
            throw new IllegalArgumentException("MongoDB aggregate option explain must be a boolean");

View on GitHub (pinned to c0390bff16)

Solutions

1. Make each array element a single-key stage object, e.g. {"$sort": {"_id": -1}}
2. Check for trailing commas or misplaced brackets that turn a stage into a non-object JSON value
3. Re-test the pipeline in mongosh before submitting it

When it happens

Trigger: Thrown at agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java:530 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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