t8y2/dbx · error · IllegalArgumentException

Invalid collation option

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.

Solutions

Pass a real boolean (true/false), not a string or number
Convert "true"/"false" strings with Boolean.parseBoolean before calling
Convert 1/0 numeric flags with (value != 0)
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}}

Defensive patterns

Strategy: type-guard

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Ensure JSON serialization preserves booleans (no "true" strings)
Convert 0/1 flags to booleans at ingestion
Coerce query-string booleans with strict parsing (only 'true'/'false')
Type-check collation configs before sending

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

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

Appendix: 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)