{"record":{"id":"a7422c54cfd08e09","repo":"quarkusio/quarkus","slug":"illegal-read-preference-configured-in-the-mongoe-a7422c","errorCode":null,"errorMessage":"Illegal read preference  configured in the @MongoEntity annotation of .. Supported values are primary|primaryPreferred|secondary|secondaryPreferred|nearest","messagePattern":"Illegal read preference  configured in the @MongoEntity annotation of \\.\\. Supported values are primary\\|primaryPreferred\\|secondary\\|secondaryPreferred\\|nearest","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/panache/mongodb-panache-common/runtime/src/main/java/io/quarkus/mongodb/panache/common/runtime/MongoOperations.java","lineNumber":196,"sourceCode":"        if (session == null) {\n            collection.deleteOne(query);\n        } else {\n            collection.deleteOne(session, query);\n        }\n    }\n\n    public MongoCollection mongoCollection(Class<?> entityClass) {\n        MongoEntity mongoEntity = entityClass.getAnnotation(MongoEntity.class);\n        MongoDatabase database = mongoDatabase(mongoEntity);\n        if (mongoEntity != null) {\n            MongoCollection collection = mongoEntity.collection().isEmpty()\n                    ? database.getCollection(entityClass.getSimpleName(), entityClass)\n                    : database.getCollection(mongoEntity.collection(), entityClass);\n            if (!mongoEntity.readPreference().isEmpty()) {\n                try {\n                    collection = collection.withReadPreference(ReadPreference.valueOf(mongoEntity.readPreference()));\n                } catch (IllegalArgumentException iae) {\n                    throw new IllegalArgumentException(\"Illegal read preference \" + mongoEntity.readPreference()\n                            + \" configured in the @MongoEntity annotation of \" + entityClass.getName() + \".\"\n                            + \" Supported values are primary|primaryPreferred|secondary|secondaryPreferred|nearest\");\n                }\n            }\n            return collection;\n        }\n        return database.getCollection(entityClass.getSimpleName(), entityClass);\n    }\n\n    public MongoDatabase mongoDatabase(Class<?> entityClass) {\n        MongoEntity mongoEntity = entityClass.getAnnotation(MongoEntity.class);\n        return mongoDatabase(mongoEntity);\n    }\n\n    //\n    // Private stuff\n\n    private void persist(MongoCollection collection, Object entity) {","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/panache/mongodb-panache-common/runtime/src/main/java/io/quarkus/mongodb/panache/common/runtime/MongoOperations.java#L178-L214","documentation":"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.","triggerScenarios":"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.","commonSituations":"Typo like \"primaryPrefered\" (missing 'r') or \"SECONDARY\"; copy-pasting readPreference names from another driver/API; trailing spaces in the annotation value.","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."],"exampleFix":"// before\n@MongoEntity(database = \"app\", collection = \"users\", readPreference = \"primaryPrefered\")\n// after\n@MongoEntity(database = \"app\", collection = \"users\", readPreference = \"primaryPreferred\")","handlingStrategy":"validation","validationCode":"// verify the annotation value at startup\nString rp = Book.class.getAnnotation(MongoEntity.class).readPreference();\nSet<String> valid = Set.of(\"primary\",\"primaryPreferred\",\"secondary\",\"secondaryPreferred\",\"nearest\");\nif (!rp.isEmpty() && !valid.contains(rp)) throw new IllegalStateException(\"Bad readPreference: \" + rp);","typeGuard":null,"tryCatchPattern":"try {\n    ReadPreference.valueOf(mongoEntity.readPreference());\n} catch (IllegalArgumentException iae) {\n    throw new IllegalArgumentException(\"Invalid @MongoEntity readPreference: \" + mongoEntity.readPreference());\n}","preventionTips":["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."],"tags":["mongodb","configuration","annotation","read-preference"],"backgroundTag":"invalid-config-value","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}