t8y2/dbx · error · java.lang.IllegalArgumentException

Each arrayFilters entry must be an object

Error message

Each arrayFilters entry must be an object

What it means

Each entry inside the `arrayFilters` array must itself be an object (a BSON Document of filter conditions for the `$[<identifier>]` positional operator). MongoAgent iterates the array and rejects any scalar, string, or array element with this IllegalArgumentException because the Java driver requires List<Document>.

Source

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

            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) {
        return updateJson.trim().startsWith("[");
    }

    static List<Document> updatePipelineForWrite(String updateJson) {
        JsonElement parsed = JsonParser.parseString(updateJson);

View on GitHub (pinned to c0390bff16)

Solutions

1. Make every arrayFilters element a JSON object: `[{"g.level": {"$gte": 90}}]`.
2. Quote field paths as keys, not expressions: use `{"g.score": {"$exists": true}}`, not `"g.score exists"`.
3. Check for null or empty string entries if arrayFilters is built dynamically.
4. Validate each element serializes as `{...}` before sending the request.

Example fix

// before
"arrayFilters": ["g.level: {$gte: 90}"]
// after
"arrayFilters": [{"g.level": {"$gte": 90}}]

// Java: every element must be a Document/map
Object af = options.get("arrayFilters");
if (af instanceof List<?> l) {
    for (Object e : l) {
        if (!(e instanceof java.util.Map))
            throw new IllegalArgumentException("Each arrayFilters entry must be an object");
    }
}

static boolean isValidArrayFilters(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 entry must be an object")) {
    // convert string entries into {path: value} documents and retry
  } else throw e;
}

When it happens

Trigger: Calling an update with `"arrayFilters": ["g.level >= 90"]` or `["g"]` — array elements are strings/numbers rather than filter documents like `[{"g.level": {"$gte": 90}}]`.

Common situations: Typing filter expressions as strings instead of documents; copy-pasting shell syntax into JSON; generating arrayFilters programmatically with wrong element type; a stray null element in the array.

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

• arrayFilters must be an array
• 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/ab4e5b23646a7c84. Report an issue: GitHub.