t8y2/dbx · error · IllegalArgumentException

Invalid collation: locale must not be empty

Error message

Invalid collation: locale must not be empty

What it means

Thrown by MongoAgent.collationOrNull while building a MongoDB Collation from the collation document: the 'locale' field was present but empty. Locale is the only mandatory collation field and an empty string is invalid, so the collation (and the query carrying it) is rejected.

Source

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

        return documentQueryResult(documents, total);
    }

    static Collation collationOrNull(Document document) {
        if (document == null) {
            return null;
        }
        Set<String> supported = Set.of(
            "locale", "strength", "caseLevel", "caseFirst", "numericOrdering",
            "alternate", "maxVariable", "normalization", "backwards"
        );
        for (String key : document.keySet()) {
            if (!supported.contains(key)) {
                throw new IllegalArgumentException("Unsupported collation option: " + key);
            }
        }
        String locale = document.getString("locale");
        if (locale == null || locale.isBlank()) {
            throw new IllegalArgumentException("Invalid collation: locale must not be empty");
        }

        Collation.Builder builder = Collation.builder().locale(locale);
        if (document.containsKey("strength")) {
            Object strength = document.get("strength");
            if (!(strength instanceof Number number) || number.doubleValue() != Math.rint(number.doubleValue())) {
                throw new IllegalArgumentException("Invalid collation option strength: expected an integer from 1 to 5");
            }
            int strengthValue = number.intValue();
            if (strengthValue < 1 || strengthValue > 5) {
                throw new IllegalArgumentException("Invalid collation option strength: expected an integer from 1 to 5");
            }
            builder.collationStrength(CollationStrength.fromInt(strengthValue));
        }
        if (document.containsKey("caseLevel")) {
            builder.caseLevel(collationBoolean(document, "caseLevel"));
        }
        if (document.containsKey("caseFirst")) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Add a valid locale string, e.g. {"locale":"en"} or "simple" for no collation
2. Check that the locale variable is populated before constructing the collation
3. Omit the collation entirely if locale is unknown
4. Normalize empty strings to null and skip collation

Example fix

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

if (!collation || typeof collation.locale !== 'string' || collation.locale.trim() === '') {
  throw new Error('collation requires a non-empty locale');
}

function hasCollationLocale(c) {
  return typeof c?.locale === 'string' && c.locale.trim().length > 0;
}

try {
  result = agent.findOne(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage() === 'Invalid collation: locale must not be empty') {
    delete params.collation;
    result = agent.findOne(params);
  } else throw e;
}

When it happens

Trigger: Passing collation {} or {"strength":2} without locale, or {"locale":""} / {"locale":" "}.

Common situations: Building collation objects conditionally and forgetting locale; templated configs where the locale variable is empty; assuming the driver defaults the locale (it does not).

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• Unsupported collation option: ${key}
• Invalid collation option strength: expected an integer from
• Invalid collation option ${key}: expected a string
• MongoDB createUser requires a non-empty user name
• 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/c5ecd446551d1bb6. Report an issue: GitHub.