t8y2/dbx · error · java.lang.IllegalArgumentException

arrayFilters must be an array

Error message

arrayFilters must be an array

What it means

MongoAgent's arrayFilters handling validates the `arrayFilters` option passed with array-field updates (updateOne/updateMany/findAndModify). The option must be a JSON array; a non-array value (object, string, number) cannot be converted to the List<Document> the MongoDB Java driver requires, so an IllegalArgumentException is thrown before any DB call.

Source

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

    }

    static UpdateOptions updateOptionsForWrite(String optionsJson) {
        UpdateOptions result = new UpdateOptions();
        if (optionsJson == null || optionsJson.trim().isEmpty()) {
            return result;
        }
        Document options = Document.parse(optionsJson);
        for (String key : options.keySet()) {
            if (!"arrayFilters".equals(key)) {
                throw new IllegalArgumentException("Unsupported update option: " + key);
            }
        }
        Object rawFilters = options.get("arrayFilters");
        if (rawFilters == null) {
            return result;
        }
        if (!(rawFilters instanceof List<?>)) {
            throw new IllegalArgumentException("arrayFilters must be an array");
        }
        List<Document> filters = new ArrayList<>();
        for (Object filter : (List<?>) rawFilters) {
            if (!(filter instanceof Document)) {
                throw new IllegalArgumentException("Each arrayFilters entry must be an object");
            }
            filters.add((Document) filter);
        }
        return result.arrayFilters(filters);
    }

    static Document documentForWrite(String docJson) {
        Document doc = Document.parse(docJson);
        convertMongoShellDates(doc);
        return doc;
    }

    private static boolean isUpdatePipelineJson(String updateJson) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass arrayFilters as a JSON array of objects: `"arrayFilters": [{"elem.age": {"$gte": 21}}]`.
2. If the value is a single filter object, wrap it in an array literal.
3. If the value is a JSON-encoded string, decode/parse it into an actual array before sending.
4. Remove the arrayFilters option entirely if the update does not use the filtered positional `$[<identifier>]` operator.

Example fix

// before
{"updateOne": {"filter": {"grades": {"$elemMatch": {"level": {"$gte": 90}}}}, "update": {"$set": {"grades.$[g].score": 100}}, "arrayFilters": {"g.level": {"$gte": 90}}}}
// after
{"updateOne": {"filter": {"grades": {"$elemMatch": {"level": {"$gte": 90}}}}, "update": {"$set": {"grades.$[g].score": 100}}, "arrayFilters": [{"g.level": {"$gte": 90}}]}}

// Java: validate before sending
Object af = options.get("arrayFilters");
if (af != null && !(af instanceof List)) {
    throw new IllegalArgumentException("arrayFilters must be an array of objects");
}

static boolean isArrayFiltersArray(Object v) { return v instanceof List<?> l && l.stream().allMatch(x -> x instanceof java.util.Map); }

try { agent.updateOne(filter, update, options); }
catch (IllegalArgumentException e) {
  if (e.getMessage().contains("arrayFilters must be an array")) {
    // normalize: wrap single object in a List and retry
  } else throw e;
}

When it happens

Trigger: Calling a MongoAgent update method with params options containing `arrayFilters` set to a non-array value, e.g. `{"arrayFilters": {"elem.age": {"$gte": 21}}}` or a JSON string instead of `[{"elem.age": {"$gte": 21}}]`.

Common situations: Hand-writing agent request JSON and confusing the object-vs-array shape of arrayFilters; porting code from drivers where arrayFilters keys look like an object; templating tools that quote the array so it arrives as a string.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Each arrayFilters entry must be an object
• MongoDB aggregate option ${key} must be a non-negative integ
• MongoDB explain verbosity must be queryPlanner, executionSta
• Unsupported findOne option: ${key}
• Unsupported collation option: ${key}

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