t8y2/dbx · error · IllegalArgumentException

Unsupported findOne option: ${key}

Error message

Unsupported findOne option: ${key}

What it means

Thrown by MongoAgent.findOne when the options document contains a key not in the supported findOne option set (filter/projection-style options). This is a strict allow-list guard: any unrecognized option key is rejected rather than silently ignored, to prevent options that would silently not apply.

Source

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

            throw new IllegalArgumentException(
                "MongoDB explain verbosity must be queryPlanner, executionStats, or allPlansExecution");
        }
        return verbosity;
    }

    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);
        }

View on GitHub (pinned to c0390bff16)

Solutions

1. Remove any options other than "sort" from the findOne options
2. Move unsupported options (e.g. projection) into the appropriate parameters of the API, if available
3. Apply limit 1 client-side after fetching, or use find with limit instead of findOne
4. Whitelist/strip keys before passing options

Example fix

// before
{"collection":"users","filter":{},"options":{"sort":{"age":1},"limit":1}}
// after
{"collection":"users","filter":{},"options":{"sort":{"age":1}}}

const ALLOWED = ['sort'];
for (const k of Object.keys(opts || {})) {
  if (!ALLOWED.includes(k)) throw new Error('findOne does not support option: ' + k);
}

function hasOnlySupportedFindOneOptions(opts) {
  return opts == null || Object.keys(opts).every(k => k === 'sort');
}

try {
  result = agent.findOne(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unsupported findOne option")) {
    params.options = { sort: params.options?.sort };
    result = agent.findOne(params);
  } else throw e;
}

When it happens

Trigger: Calling findOne with options such as {"limit":1}, {"projection":{...}}, {"maxTimeMS":...}, or any key other than "sort".

Common situations: Copying option objects from find() calls (which support many options) into findOne; assuming findOne supports limit/projection; forwarding raw client-supplied option objects.

Related errors

• Unsupported collation option: ${key}
• Unsupported MongoDB aggregate cursor option: ${key}
• Unsupported MongoDB Legacy aggregate option: ${key}
• MongoDB aggregate option ${key} must be a non-negative integ
• MongoDB explain verbosity must be queryPlanner, executionSta

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