t8y2/dbx · error · IllegalArgumentException

Invalid findOne option sort: expected an object

Error message

Invalid findOne option sort: expected an object

What it means

When findOne is given options.sort, the value must be a MongoDB Document (an object) mapping field names to sort directions. If 'sort' is present but is not an object (e.g. a string or array), this error is thrown.

Source

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

    private static Object findOne(JsonObject params) {
        MongoClient c = requireClient();
        String database = params.get("database").getAsString();
        String collection = params.get("collection").getAsString();
        Document filter = documentOrNull(params, "filter");
        Document projection = documentOrNull(params, "projection");
        Document options = documentOrNull(params, "options");
        Document sort = null;

        if (options != null) {
            for (String key : options.keySet()) {
                if (!"sort".equals(key)) {
                    throw new IllegalArgumentException("Unsupported findOne option: " + key);
                }
            }
            Object rawSort = options.get("sort");
            if (rawSort != null) {
                if (!(rawSort instanceof Document sortDocument)) {
                    throw new IllegalArgumentException("Invalid findOne option sort: expected an object");
                }
                sort = sortDocument;
            }
        }

        var iterable = c.getDatabase(database).getCollection(collection).find(filter == null ? new Document() : filter);
        if (projection != null) {
            iterable = iterable.projection(projection);
        }
        if (sort != null) {
            iterable = iterable.sort(sort);
        }
        Document document = iterable.limit(1).first();

        List<Map<String, Object>> documents = new ArrayList<>();
        List<JsonObject> extendedDocuments = new ArrayList<>();
        if (document != null) {
            documents.add(bsonToJson(document));

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass sort as an object: {"field":1} for ascending, {"field":-1} for descending
2. Convert array-of-tuples sort formats into an object before calling
3. Omit options.sort entirely if no sorting is needed
4. Parse/normalize sort input from clients into a Document

Example fix

// before
{"collection":"users","options":{"sort":"name"}}
// after
{"collection":"users","options":{"sort":{"name":1}}}

if (opts && opts.sort != null && (typeof opts.sort !== 'object' || Array.isArray(opts.sort))) {
  throw new Error('sort must be an object like {field: 1}');
}

function isSortDocument(v) {
  return v == null || (typeof v === 'object' && !Array.isArray(v));
}

try {
  result = agent.findOne(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage() === 'Invalid findOne option sort: expected an object') {
    delete params.options.sort;
    result = agent.findOne(params);
  } else throw e;
}

When it happens

Trigger: Calling findOne with options.sort as a string like "name", a JSON array like [["name",1]], or null-coerced primitives.

Common situations: Passing MongoDB shell-style sort strings; passing SQL-style 'ORDER BY name' strings; arrays of tuples from other driver conventions; JSON where sort was serialized as a string.

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

• Unsupported findOne option: ${key}
• Invalid collation option ${key}: expected a boolean
• dropIndex only accepts a string index name or JSON document
• dropIndexes only accepts a string index name, JSON document,
• Client certificate and key must be provided together

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