t8y2/dbx · error · IllegalArgumentException

Invalid collation option ${key}: expected a string

Error message

Invalid collation option ${key}: expected a string

What it means

MongoAgent.collationString reads a collation option (e.g. locale, strength) from the request document and requires it to be a String, because the MongoDB collation document maps option names to string values. When a caller supplies a collation option whose value is not a JSON string (e.g. a number or object), the driver throws IllegalArgumentException before any query runs. It is a client-side input validation error protecting the server from a malformed collation document.

Source

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

            builder.backwards(collationBoolean(document, "backwards"));
        }
        return builder.build();
    }

    private static boolean collationBoolean(Document document, String key) {
        Object value = document.get(key);
        if (value instanceof Boolean booleanValue) {
            return booleanValue;
        }
        throw new IllegalArgumentException("Invalid collation option " + key + ": expected a boolean");
    }

    private static String collationString(Document document, String key) {
        Object value = document.get(key);
        if (value instanceof String stringValue) {
            return stringValue;
        }
        throw new IllegalArgumentException("Invalid collation option " + key + ": expected a string");
    }

    static CollectionTotal collectionTotal(MongoCollection<Document> collection, Document filter) {
        return collectionTotal(collection, filter, null);
    }

    static CollectionTotal collectionTotal(MongoCollection<Document> collection, Document filter, Collation collation) {
        if (filter.isEmpty()) {
            return new CollectionTotal(collection.estimatedDocumentCount(), false);
        }
        CountOptions options = new CountOptions();
        if (collation != null) {
            options.collation(collation);
        }
        return new CollectionTotal(collection.countDocuments(filter, options), true);
    }

    static Map<String, Object> documentQueryResult(List<?> documents, CollectionTotal total) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Find the collation option named in the message and change its value to a string (e.g. "strength": "2", "caseLevel": "true" depending on the agent's expected schema).
2. Check which API call you made and how its collation document is built; ensure all values passed under collation keys are JSON strings.
3. If you don't need case/diacritic-sensitive comparison, drop the collation option entirely so the default collation is used.

Example fix

// before
{"find": "users", "filter": {}, "collation": {"locale": "en", "strength": 2}}
// after
{"find": "users", "filter": {}, "collation": {"locale": "en", "strength": "2"}}

// JS caller
function validateCollation(collation) {
  if (collation == null) return true;
  return Object.entries(collation).every(([k, v]) => typeof v === "string");
}
// e.g. fix: collation.strength = String(collation.strength);

function isStringCollation(c) {
  return c == null || Object.values(c).every(v => typeof v === "string");
}

try {
  await agent.find({ database, collection, filter, collation });
} catch (e) {
  if (String(e.message).includes("Invalid collation option")) {
    // coerce offending option to string and retry once
  } else throw e;
}

When it happens

Trigger: Calling a query/aggregate/count operation with a collation document where an option value is a non-string JSON type, e.g. {"collation": {"strength": 2}} or {"caseLevel": true} passed through the collation options document.

Common situations: Copying a collation example where strength or numericOrdering are given as numbers; hand-writing collation JSON where booleans/ints slip in; older code that predates correct collation typing.

Related errors

• Unsupported collation option: ${key}
• Invalid collation: locale must not be empty
• Invalid collation option strength: expected an integer from
• Index option "name" must be a non-empty string
• MongoDB aggregate option ${key} must be a non-negative integ

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