t8y2/dbx · error · IllegalArgumentException

Unsupported MongoDB Legacy aggregate option: ${key}

Error message

Unsupported MongoDB Legacy aggregate option: ${key}

What it means

validateAggregateOptions enforces a whitelist of supported aggregate options (allowDiskUse, bypassDocumentValidation, collation, comment, hint, useCursor, explain, cursor, etc.). Any top-level options key outside the supported set throws IllegalArgumentException so unsupported options are never silently ignored.

Source

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

        return iterable;
    }

    private static void validateAggregateOptions(Document options) {
        Set<String> supported = Set.of(
            "explain",
            "allowDiskUse",
            "cursor",
            "maxTimeMS",
            "maxAwaitTimeMS",
            "bypassDocumentValidation",
            "collation",
            "comment",
            "hint",
            "useCursor"
        );
        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;

View on GitHub (pinned to c0390bff16)

Solutions

1. Remove or correct the offending key — check spelling against the supported list in validateAggregateOptions.
2. Move functionality to a supported option (e.g. use batchSize under cursor, or hint) or drop it.
3. Update/upgrade the agent to a version that whitelists the option you need.
4. Validate the options payload client-side against the same whitelist before sending.

Example fix

// before
Document options = new Document("allowDisUse", true); // typo
// after
Document options = new Document("allowDiskUse", true);

static final Set<String> SUPPORTED = Set.of("explain","cursor","allowDiskUse","bypassDocumentValidation","collation","comment","hint","useCursor");
for (String key : options.keySet()) {
    if (!SUPPORTED.contains(key)) throw new IllegalArgumentException("Unsupported aggregate option: " + key);
}

static boolean allKeysSupported(Document options, Set<String> supported) {
    return supported.containsAll(options.keySet());
}

try {
    agent.aggregate(db, collection, pipeline, options);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unsupported MongoDB Legacy aggregate option")) {
        String badKey = e.getMessage().substring(e.getMessage().lastIndexOf(':') + 2);
        options.remove(badKey);
        // retry with sanitized options, or surface a typed config error
    } else throw e;
}

When it happens

Trigger: Calling aggregate with options containing a misspelled or unsupported key, e.g. {"allowDisUse":true}, {"maxTimeMS":5000}, or {"let":{...}} on a version of the agent whose whitelist lacks it.

Common situations: Typo'd option names; options copied from the MongoDB server aggregate command spec that this agent wrapper does not map; config files grown over time that carry options valid for other drivers/versions.

Related errors

• Unsupported MongoDB aggregate cursor 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/257ddcf73bc3291d. Report an issue: GitHub.