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

When @MongoEntity(readPreference=...) is set on an entity, MongoOperations applies it via ReadPreference.valueOf(). If the string is not one of primary|primaryPreferred|secondary|secondaryPreferred|nearest, the driver throws IllegalArgumentException, which is rethrown with this explanatory message naming the entity class.

Source

Thrown at extensions/panache/mongodb-panache-common/runtime/src/main/java/io/quarkus/mongodb/panache/common/runtime/MongoOperations.java:196

        if (session == null) {
            collection.deleteOne(query);
        } else {
            collection.deleteOne(session, query);
        }
    }

    public MongoCollection mongoCollection(Class<?> entityClass) {
        MongoEntity mongoEntity = entityClass.getAnnotation(MongoEntity.class);
        MongoDatabase database = mongoDatabase(mongoEntity);
        if (mongoEntity != null) {
            MongoCollection 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 MongoDatabase mongoDatabase(Class<?> entityClass) {
        MongoEntity mongoEntity = entityClass.getAnnotation(MongoEntity.class);
        return mongoDatabase(mongoEntity);
    }

    //
    // Private stuff

    private void persist(MongoCollection collection, Object entity) {

View on GitHub (pinned to e1c734241f)

Solutions

Fix the readPreference value in @MongoEntity to exactly one of primary, primaryPreferred, secondary, secondaryPreferred, nearest.
Remove the readPreference attribute to use the default (primary).
Configure read preference globally via quarkus.mongodb.read-preference instead of per-entity.

Example fix

// before
@MongoEntity(database = "app", collection = "users", readPreference = "primaryPrefered")
// after
@MongoEntity(database = "app", collection = "users", readPreference = "primaryPreferred")

Defensive patterns

Strategy: validation

Validate before calling

// verify the annotation value at startup
String rp = Book.class.getAnnotation(MongoEntity.class).readPreference();
Set<String> valid = Set.of("primary","primaryPreferred","secondary","secondaryPreferred","nearest");
if (!rp.isEmpty() && !valid.contains(rp)) throw new IllegalStateException("Bad readPreference: " + rp);

Try / catch

try {
    ReadPreference.valueOf(mongoEntity.readPreference());
} catch (IllegalArgumentException iae) {
    throw new IllegalArgumentException("Invalid @MongoEntity readPreference: " + mongoEntity.readPreference());
}

Prevention

Copy readPreference strings exactly from driver docs: primary|primaryPreferred|secondary|secondaryPreferred|nearest.
Add a startup smoke test that touches each annotated entity's collection.
Prefer quarkus.mongodb.read-preference config over per-entity annotations for global settings.

When it happens

Trigger: Starting the app (first collection access for the entity) with an @MongoEntity annotation whose readPreference value is misspelled, empty-matching (non-empty but invalid), wrongly cased, or contains whitespace.

Common situations: Typo like "primaryPrefered" (missing 'r') or "SECONDARY"; copy-pasting readPreference names from another driver/API; trailing spaces in the annotation value.

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

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