t8y2/dbx · error · IllegalArgumentException

Invalid collation option strength: expected an integer from

Error message

Invalid collation option strength: expected an integer from 1 to 5

What it means

The collation 'strength' option must be an integer from 1 to 5 per the MongoDB/ICU spec. If the value is not a number or has a fractional part, this error is thrown (the range check produces the same message).

Source

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

        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")) {
            builder.collationCaseFirst(CollationCaseFirst.fromString(collationString(document, "caseFirst")));
        }
        if (document.containsKey("numericOrdering")) {
            builder.numericOrdering(collationBoolean(document, "numericOrdering"));
        }
        if (document.containsKey("alternate")) {
            builder.collationAlternate(CollationAlternate.fromString(collationString(document, "alternate")));

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass strength as an integer number: 1, 2, 3, 4, or 5
2. Convert string values with Integer.parseInt before calling
3. Map textual levels (primary/secondary/tertiary/quaternary/identical) to 1-5
4. Omit strength to use the default level 3

Example fix

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

if (collation.strength != null) {
  const s = Number(collation.strength);
  if (!Number.isInteger(s) || s < 1 || s > 5) throw new Error('strength must be an integer 1-5');
}

function isValidCollationStrength(v) {
  return v == null || (typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= 5);
}

try {
  result = agent.findOne(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage().includes('collation option strength')) {
    params.collation.strength = 3;
    result = agent.findOne(params);
  } else throw e;
}

When it happens

Trigger: Passing strength as a string ("2"), a float (1.5), a boolean, or null while the key is present.

Common situations: Reading strength from text config or query strings where everything is a string; copying ICU level names like 'primary' instead of the numeric value 1; decimal separators.

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 collation option: ${key}
• Invalid collation: locale must not be empty
• Invalid collation option ${key}: expected a string
• 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/a951e4a4eeb87ade. Report an issue: GitHub.