quarkusio/quarkus · error · IllegalArgumentException

Illegal read preference configured in the @MongoEntity anno

Error message

Illegal read preference  configured in the @MongoEntity annotation of .. Supported values are primary|primaryPreferred|secondary|secondaryPreferred|nearest

What it means

mongoCollection() applies the @MongoEntity annotation's readPreference by calling ReadPreference.valueOf(); if that value is not one of the MongoDB driver's known names, the driver throws IllegalArgumentException, which Panache re-throws with a message listing the supported values: primary, primaryPreferred, secondary, secondaryPreferred, nearest.

Source

Thrown at extensions/panache/mongodb-panache-common/runtime/src/main/java/io/quarkus/mongodb/panache/common/reactive/runtime/ReactiveMongoOperations.java:230

        if (Panache.getCurrentSession() != null) {
            return collection.deleteOne(Panache.getCurrentSession(), query).onItem().ignore().andContinueWithNull();
        }
        return collection.deleteOne(query).onItem().ignore().andContinueWithNull();
    }

    public ReactiveMongoCollection mongoCollection(Class<?> entityClass) {
        MongoEntity mongoEntity = entityClass.getAnnotation(MongoEntity.class);
        ReactiveMongoDatabase database = mongoDatabase(mongoEntity);
        if (mongoEntity != null) {
            ReactiveMongoCollection collection = mongoEntity.collection().isEmpty()
                    ? database.getCollection(entityClass.getSimpleName(), entityClass)
                    : database.getCollection(mongoEntity.collection(), entityClass);
            if (!mongoEntity.readPreference().isEmpty()) {
                try {
                    collection = collection.withReadPreference(ReadPreference.valueOf(mongoEntity.readPreference()));
                } catch (IllegalArgumentException iae) {
                    throw new IllegalArgumentException("Illegal read preference " + mongoEntity.readPreference()
                            + " configured in the @MongoEntity annotation of " + entityClass.getName() + "."
                            + " Supported values are primary|primaryPreferred|secondary|secondaryPreferred|nearest");
                }
            }
            return collection;
        }
        return database.getCollection(entityClass.getSimpleName(), entityClass);
    }

    public ReactiveMongoDatabase mongoDatabase(Class<?> entityClass) {
        MongoEntity mongoEntity = entityClass.getAnnotation(MongoEntity.class);
        return mongoDatabase(mongoEntity);
    }

    //
    // Private stuff

    public Uni<Void> nullUni() {

View on GitHub (pinned to e1c734241f)

Solutions

1. Set readPreference to exactly one of: primary, primaryPreferred, secondary, secondaryPreferred, nearest (case is handled by valueOf but spelling must match)
2. Verify the annotation on the entity class referenced in the error message (entityClass.getName())
3. If you need driver-specific tags/read-preference behavior, configure it on the MongoClient instead of the annotation

Example fix

// before
@MongoEntity(collection = "orders", readPreference = "secondary-preferred")

// after
@MongoEntity(collection = "orders", readPreference = "secondaryPreferred")

private static final Set<String> VALID_RP = Set.of("primary","primaryPreferred","secondary","secondaryPreferred","nearest");
String rp = entityAnnotation.readPreference();
if (!rp.isEmpty() && !VALID_RP.contains(rp)) {
    throw new IllegalArgumentException("Bad readPreference: " + rp);
}

When it happens

Trigger: Setting @MongoEntity(readPreference = "...") to a misspelled or unsupported value (e.g. 'Primary', 'primary ', 'majority', 'secondary-preferred') on an entity class, then running any query/update that resolves the collection.

Common situations: Typos or wrong casing in the annotation; using dash-instead-of-camelCase ('secondary-preferred'); copying readPreference strings from MongoDB connection-string options that use different naming; misremembering 'nearest' as 'closest'.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Illegal read preference configured in the @MongoEntity anno
• The database was not configured for the default Mongo Client
• The database attribute was not set for the @MongoEntity anno
• The database attribute was not set for the @MongoEntity anno
• The configuration ${clazz} is missing the @ConfigRoot annota

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/40d12ccfe54919dd. Report an issue: GitHub.