t8y2/dbx · error · IllegalArgumentException

Invalid collation option ${key}: expected a boolean

Error message

Invalid collation option ${key}: expected a boolean

What it means

Boolean collation options (caseLevel, caseFirst-related toggles like backwards, normalization, numericOrdering) are read via collationBoolean, which requires the value to be an actual Boolean. Any other type throws this error naming the offending key.

Source

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

        }
        if (document.containsKey("maxVariable")) {
            builder.collationMaxVariable(CollationMaxVariable.fromString(collationString(document, "maxVariable")));
        }
        if (document.containsKey("normalization")) {
            builder.normalization(collationBoolean(document, "normalization"));
        }
        if (document.containsKey("backwards")) {
            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);
        }

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass a real boolean (true/false), not a string or number
2. Convert "true"/"false" strings with Boolean.parseBoolean before calling
3. Convert 1/0 numeric flags with (value != 0)
4. Remove the key to use the default (false for these flags)

Example fix

// before
{"collation":{"locale":"en","caseLevel":"true"}}
// after
{"collation":{"locale":"en","caseLevel":true}}

const BOOL_KEYS = ['caseLevel','numericOrdering','normalization','backwards'];
for (const k of BOOL_KEYS) {
  if (collation[k] != null && typeof collation[k] !== 'boolean') {
    throw new Error('collation.' + k + ' must be a boolean');
  }
}

function isBoolean(v) {
  return typeof v === 'boolean';
}

try {
  result = agent.findOne(params);
} catch (IllegalArgumentException e) {
  if (e.getMessage().includes('expected a boolean')) {
    const key = e.getMessage().match(/option (\w+):/)[1];
    params.collation[key] = params.collation[key] === 'true' || params.collation[key] === 1;
    result = agent.findOne(params);
  } else throw e;
}

When it happens

Trigger: Passing e.g. {"caseLevel":"true"}, {"numericOrdering":1}, or {"backwards":null} in a collation document.

Common situations: JSON configs where booleans were serialized as strings; 0/1 integer flags from other systems; templating that stringifies values.

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

• MongoDB aggregate option collation must be an object
• Invalid findOne option sort: expected an object
• Unsupported collation option: ${key}
• Invalid collation: locale must not be empty
• Invalid collation option strength: expected an integer from

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