t8y2/dbx · error · IllegalArgumentException

MongoDB aggregate option ${key} is too large

Error message

MongoDB aggregate option ${key} is too large

What it means

aggregateNonNegativeInt converts an aggregate option value (e.g. cursor batchSize) from long to int; if the long exceeds Integer.MAX_VALUE it throws IllegalArgumentException naming the key. Values below zero would already have been rejected by aggregateNonNegativeLong. This guards the narrowing cast.

Source

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

        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();
        if (result < 0) {
            throw new IllegalArgumentException("MongoDB aggregate option " + key + " must be a non-negative integer");
        }
        return result;
    }

    static Document buildFindExplainCommand(JsonObject params) {
        String collection = params.get("collection").getAsString();

View on GitHub (pinned to c0390bff16)

Solutions

1. Use a realistic batchSize within int range, e.g. 100–10000 documents.
2. Clamp client-side: Math.min(value, Integer.MAX_VALUE) before sending.
3. If a very large batch was intended, page through results in multiple calls instead.
4. Sanitize numeric config at load time with explicit range checks.

Example fix

// before
long batchSize = 1L << 40; // far beyond int range
// after
int batchSize = (int) Math.min(rawBatchSize, 10000L);

Object bs = cursorDoc.get("batchSize");
if (bs instanceof Number n && (n.longValue() < 0 || n.longValue() > Integer.MAX_VALUE)) {
    throw new IllegalArgumentException("batchSize must fit in a non-negative int");
}

static boolean isIntSafe(Object v) {
    return v instanceof Number n && n.longValue() >= 0 && n.longValue() <= Integer.MAX_VALUE;
}

try {
    agent.aggregate(db, collection, pipeline, options);
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith("is too large")) {
        String key = e.getMessage().replaceFirst(".* option ", "").replace(" is too large", "");
        Document doc = (Document) options.get("cursor");
        doc.put(key, Math.min(((Number) doc.get(key)).longValue(), 10000L).intValue());
        // retry with clamped value
    } else throw e;
}

When it happens

Trigger: Calling aggregate with {"cursor":{"batchSize": 99999999999}} — any batchSize (or other int-typed option) larger than 2147483647.

Common situations: Copy-pasted placeholder values like 2^40 as a 'max' batch size; JSON numbers parsed as long; misconfigured tooling that multiplies values (e.g. MB-to-bytes conversion on a batch-size setting).

Related errors

• MongoDB aggregate limit must be between 0 and ${Integer.MAX_
• MongoDB aggregate option explain must be a boolean
• MongoDB aggregate option cursor must be an object
• Unsupported MongoDB aggregate cursor option: ${key}
• MongoDB aggregate option collation must be an object

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