t8y2/dbx · error · IllegalArgumentException

MongoDB aggregate pipeline must be a JSON array

Error message

MongoDB aggregate pipeline must be a JSON array

What it means

Thrown by MongoAgent.aggregatePipeline after successfully JSON-parsing the 'pipeline' parameter when the top-level parsed element is not a JSON array (e.g. an object or scalar). MongoDB aggregation pipelines must be arrays of stage documents, so the shape is rejected.

Source

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

                extendedDocuments.add(bsonToExtendedJson(document));
            }
        }
        long total = documents.size();
        if (documents.size() > maxRows) {
            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");

View on GitHub (pinned to c0390bff16)

Solutions

1. Wrap stages in square brackets: pipeline must be "[ {stage1}, {stage2} ]"
2. Remove any stray object or string wrapper around the stage array
3. Validate the value with a JSON linter before sending

When it happens

Trigger: Thrown at agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java:525 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/f08412f9e37fd6bb. Report an issue: GitHub.