t8y2/dbx · error · IllegalArgumentException

Unsupported MongoDB aggregate cursor option: ${key}

Error message

Unsupported MongoDB aggregate cursor option: ${key}

What it means

Inside the cursor option object only the key 'batchSize' is supported by this agent; any other key inside cursor{} is rejected with IllegalArgumentException because there is no mapping to the MongoDB driver's AggregateIterable. This is a whitelist check guarding against silently ignored options.

Source

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

        return command;
    }

    private static AggregateIterable<Document> applyAggregateOptions(
        AggregateIterable<Document> iterable,
        Document options
    ) {
        validateAggregateOptions(options);
        if (options.containsKey("allowDiskUse")) {
            iterable = iterable.allowDiskUse(aggregateBoolean(options, "allowDiskUse"));
        }
        if (options.containsKey("cursor")) {
            Object rawCursor = options.get("cursor");
            if (!(rawCursor instanceof Document cursor)) {
                throw new IllegalArgumentException("MongoDB aggregate option cursor must be an object");
            }
            for (String key : cursor.keySet()) {
                if (!"batchSize".equals(key)) {
                    throw new IllegalArgumentException("Unsupported MongoDB aggregate cursor option: " + key);
                }
            }
            if (cursor.containsKey("batchSize")) {
                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"));
        }

View on GitHub (pinned to c0390bff16)

Solutions

1. Keep only batchSize inside the cursor object; remove all other cursor sub-keys.
2. Move supported concerns to top-level aggregate options (e.g. maxTimeMS→ maxTime if supported) or drop them.
3. Check the driver AggregateIterable API for the feature you need and upgrade the agent if it lacks support.
4. Wrap cursor sub-options behind a whitelist check on the client side before sending.

Example fix

// before
Document options = new Document("cursor", new Document("batchSize", 100).append("maxTimeMS", 5000));
// after
Document options = new Document("cursor", new Document("batchSize", 100));

Document cursor = (Document) options.get("cursor");
if (cursor != null) {
    for (String key : cursor.keySet()) {
        if (!"batchSize".equals(key)) throw new IllegalArgumentException("Unsupported cursor option: " + key);
    }
}

static boolean hasOnlySupportedCursorKeys(Document cursor) {
    return cursor == null || cursor.keySet().stream().allMatch("batchSize"::equals);
}

try {
    agent.aggregate(db, collection, pipeline, options);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unsupported MongoDB aggregate cursor option")) {
        ((Document) options.get("cursor")).keySet().retainAll(List.of("batchSize"));
        // retry with cleaned cursor
    } else throw e;
}

When it happens

Trigger: Calling aggregate with {"cursor":{"batchSize":100,"awaitData":true}} or {"cursor":{"maxTimeMS":5000}} — any cursor sub-key other than batchSize.

Common situations: Copying cursor options from the MongoDB server command spec (e.g. awaitData, maxTimeMS, tailable) which the driver's AggregateIterable does not expose via cursor{} in this agent; leftover options from a mongodump/mongotop config.

Related errors

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

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