t8y2/dbx · error · IllegalArgumentException

MongoDB aggregate option ${key} must be a boolean

Error message

MongoDB aggregate option ${key} must be a boolean

What it means

Thrown while validating MongoDB aggregate options when option 'key' is expected to be a boolean (e.g. allowDiskUse) but the JSON value is a string, number, or object. The aggregate helper type-checks known boolean options and rejects the request before building the AggregateOptions.

Source

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

        for (String key : options.keySet()) {
            if (!supported.contains(key)) {
                throw new IllegalArgumentException("Unsupported MongoDB Legacy aggregate option: " + key);
            }
        }
    }

    private static int aggregateMaxRows(JsonObject params) {
        long value = params.has("limit") ? params.get("limit").getAsLong() : 100;
        if (value < 0 || value > Integer.MAX_VALUE) {
            throw new IllegalArgumentException("MongoDB aggregate limit must be between 0 and " + Integer.MAX_VALUE);
        }
        return (int) value;
    }

    private static boolean aggregateBoolean(Document options, String key) {
        Object value = options.get(key);
        if (!(value instanceof Boolean)) {
            throw new IllegalArgumentException("MongoDB aggregate option " + key + " must be a boolean");
        }
        return (Boolean) value;
    }

    private static int aggregateNonNegativeInt(Document options, String key) {
        long value = aggregateNonNegativeLong(options, key);
        if (value > Integer.MAX_VALUE) {
            throw new IllegalArgumentException("MongoDB aggregate option " + key + " is too large");
        }
        return (int) value;
    }

    private static long aggregateNonNegativeLong(Document options, String key) {
        Object value = options.get(key);
        if (!(value instanceof Number number) || number.doubleValue() != Math.rint(number.doubleValue())) {
            throw new IllegalArgumentException("MongoDB aggregate option " + key + " must be a non-negative integer");
        }
        long result = number.longValue();

View on GitHub (pinned to c0390bff16)

Solutions

  1. Send the option as a JSON boolean (true/false), not "true" or 1
  2. Check the option name spelling so the value lands under the intended key
Defensive patterns

Strategy: validation

Validate before calling

for (String key : List.of("allowDiskUse", "bypassDocumentValidation", "useCursor")) {
    Object v = options.get(key);
    if (v != null && !(v instanceof Boolean)) {
        throw new IllegalArgumentException(key + " must be a boolean, got: " + v.getClass().getSimpleName());
    }
}

Type guard

static boolean isBoolean(Object v) {
    return v == null || v instanceof Boolean;
}

Try / catch

try {
    agent.aggregate(db, collection, pipeline, options);
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith("must be a boolean")) {
        // identify key from message and coerce with Boolean.parseBoolean, then retry
    } else throw e;
}

Prevention

When it happens

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