t8y2/dbx · error · IllegalArgumentException

MongoDB aggregate option ${key} must be a non-negative integ

Error message

MongoDB aggregate option ${key} must be a non-negative integer

What it means

MongoAgent validates aggregate options such as batchSize, maxTimeMS, maxAwaitTimeMS, or allowDiskUse-sized values with this helper. The option must be a Number whose value is a whole number and not negative. Anything else (string, fractional, negative, non-number type) throws this IllegalArgumentException before the command is sent to MongoDB.

Source

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

        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();
        Document find = new Document("find", collection);
        Document filter = documentOrNull(params, "filter");
        find.append("filter", filter == null ? new Document() : filter);

        Document projection = documentOrNull(params, "projection");
        if (projection != null) {
            find.append("projection", projection);
        }

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass the option as an actual integer number type, not a string
2. Ensure the value is a whole number (no fractional part)
3. Clamp or omit negative values; check value >= 0 before calling
4. Validate options in the caller before sending to the agent

Example fix

// before
{"collection":"orders","pipeline":[],"options":{"batchSize":"100"}}
// after
{"collection":"orders","pipeline":[],"options":{"batchSize":100}}

function isValidNonNegativeInt(v) {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0;
}
// before calling: if (opts.batchSize != null && !isValidNonNegativeInt(opts.batchSize)) throw ...

function isNonNegativeInteger(v) {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0;
}

try {
  result = agent.aggregate(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("must be a non-negative integer")) {
    // sanitize options and retry once with defaults
  } else throw e;
}

When it happens

Trigger: Calling the aggregate operation with options like batchSize or maxTimeMS passed as a string (e.g. "1000"), as a float (e.g. 100.5), or as a negative number (e.g. -1).

Common situations: Options parsed from JSON/HTTP query params where numbers arrive as strings; copying batchSize values from shell examples that allow negatives or floats; config files edited by hand.

Understand the failure class

Background: Invalid option value errors: "must be one of", "is not a valid", and "only allows" failures explained — this error's family across 23 libraries.

Related errors

• 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
• MongoDB aggregate option comment must be a string

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