t8y2/dbx · error · IllegalArgumentException

MongoDB aggregate option collation must be an object

Error message

MongoDB aggregate option collation must be an object

What it means

Shared helper aggregateBoolean(options,key) requires the named aggregate option (allowDiskUse, bypassDocumentValidation, useCursor) to be a Boolean because it is returned directly to driver methods like allowDiskUse(boolean). A non-boolean value fails instanceof Boolean and throws IllegalArgumentException with the offending key in the message.

Source

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

                iterable = iterable.batchSize(aggregateNonNegativeInt(cursor, "batchSize"));
            }
        }
        if (options.containsKey("maxTimeMS")) {
            iterable = iterable.maxTime(aggregateNonNegativeLong(options, "maxTimeMS"), TimeUnit.MILLISECONDS);
        }
        if (options.containsKey("maxAwaitTimeMS")) {
            iterable = iterable.maxAwaitTime(
                aggregateNonNegativeLong(options, "maxAwaitTimeMS"),
                TimeUnit.MILLISECONDS
            );
        }
        if (options.containsKey("bypassDocumentValidation")) {
            iterable = iterable.bypassDocumentValidation(aggregateBoolean(options, "bypassDocumentValidation"));
        }
        if (options.containsKey("collation")) {
            Object rawCollation = options.get("collation");
            if (!(rawCollation instanceof Document collation)) {
                throw new IllegalArgumentException("MongoDB aggregate option collation must be an object");
            }
            iterable = iterable.collation(collationOrNull(collation));
        }
        if (options.containsKey("comment")) {
            Object comment = options.get("comment");
            if (!(comment instanceof String)) {
                throw new IllegalArgumentException("MongoDB aggregate option comment must be a string");
            }
            iterable = iterable.comment((String) comment);
        }
        if (options.containsKey("hint")) {
            Object hint = options.get("hint");
            if (!(hint instanceof Document)) {
                throw new IllegalArgumentException("MongoDB Legacy aggregate option hint must be an object");
            }
            iterable = iterable.hint((Document) hint);
        }
        if (options.containsKey("useCursor")) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Set the flag as an actual boolean: true/false unquoted in JSON or Boolean.TRUE in Java.
2. Coerce strings with Boolean.parseBoolean (or strict "true"/"false" parsing) before building options.
3. Remove the option if the default (false) behavior is fine.
4. Validate option types client-side before invoking the agent.

Example fix

// before
Document options = new Document("allowDiskUse", "true");
// after
Document options = new Document("allowDiskUse", Boolean.parseBoolean(String.valueOf(rawFlag)));

Object collation = options.get("collation");
if (collation != null && !(collation instanceof Document)) {
    throw new IllegalArgumentException("collation must be an object with a locale, e.g. {locale:'en_US'}");
}

static boolean isDocument(Object v) {
    return v == null || v instanceof Document;
}

try {
    agent.aggregate(db, collection, pipeline, options);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("collation must be an object")) {
        Object raw = options.get("collation");
        options.put("collation", new Document("locale", String.valueOf(raw)));
        // retry
    } else throw e;
}

When it happens

Trigger: Calling aggregate with e.g. {"allowDiskUse":"true"}, {"bypassDocumentValidation":1}, or {"useCursor":"yes"} — any non-Boolean, non-null value under one of these keys (missing keys are skipped by containsKey guards).

Common situations: Flags sourced from string env vars or query params without conversion; YAML/JSON config with quoted booleans; template rendering that stringified true/false; producers in JavaScript where 1/0 were used.

Related errors

• MongoDB aggregate option explain must be a boolean
• MongoDB aggregate option cursor must be an object
• MongoDB aggregate option comment must be a string
• MongoDB Legacy aggregate option hint must be an object
• Unsupported MongoDB aggregate cursor option: ${key}

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