{"record":{"id":"6b14e3f01a9b83e9","repo":"quarkusio/quarkus","slug":"there-should-be-only-one-result","errorCode":null,"errorMessage":"There should be only one result","messagePattern":"There should be only one result","errorType":"exception","errorClass":"PanacheQueryException","httpStatus":null,"severity":"error","filePath":"extensions/panache/mongodb-panache-common/runtime/src/main/java/io/quarkus/mongodb/panache/common/reactive/runtime/CommonReactivePanacheQueryImpl.java","lineNumber":216,"sourceCode":"    }\n\n    public <T extends Entity> Uni<Optional<T>> firstResultOptional() {\n        FindOptions options = buildOptions(1);\n        Multi<T> results = Panache.getCurrentSession() != null\n                ? collection.find(Panache.getCurrentSession(), getQuery(), options)\n                : collection.find(getQuery(), options);\n        return results.collect().first().map(o -> Optional.ofNullable(o));\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    public <T extends Entity> Uni<T> singleResult() {\n        FindOptions options = buildOptions(2);\n        Multi<T> results = Panache.getCurrentSession() != null\n                ? collection.find(Panache.getCurrentSession(), getQuery(), options)\n                : collection.find(getQuery(), options);\n        return results.collect().asList().map(list -> {\n            if (list.size() != 1) {\n                throw new PanacheQueryException(\"There should be only one result\");\n            } else {\n                return list.get(0);\n            }\n        });\n    }\n\n    public <T extends Entity> Uni<Optional<T>> singleResultOptional() {\n        FindOptions options = buildOptions(2);\n        Multi<T> results = Panache.getCurrentSession() != null\n                ? collection.find(Panache.getCurrentSession(), getQuery(), options)\n                : collection.find(getQuery(), options);\n        return results.collect().asList().map(list -> {\n            if (list.size() == 2) {\n                throw new PanacheQueryException(\"There should be no more than one result\");\n            }\n            return list.isEmpty() ? Optional.empty() : Optional.of(list.get(0));\n        });\n    }","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/panache/mongodb-panache-common/runtime/src/main/java/io/quarkus/mongodb/panache/common/reactive/runtime/CommonReactivePanacheQueryImpl.java#L198-L234","documentation":"singleResult() fetches up to 2 rows (buildOptions(2)) and throws PanacheQueryException unless exactly one entity is returned. It exists for queries that must, by domain rules, match exactly one document; zero results or two-plus results are both treated as errors rather than silently returning null or the first row.","triggerScenarios":"Calling singleResult() on a query whose filter matches 0 documents (list.size() != 1) or more than 1 document.","commonSituations":"Lookup by a field expected to be unique (email, code) that is not actually uniquely indexed in MongoDB, so duplicates were inserted; querying before the record exists (race or wrong tenant/database); overly broad filter matching several documents.","solutions":["Check whether zero results are legitimate and switch to singleResultOptional() or firstResult() if an empty match is acceptable","Add a unique index on the filter field (or use upsert semantics) to guarantee at most one document","Narrow the filter criteria so exactly one document matches, and verify you are connected to the intended database/collection"],"exampleFix":"// before\nItem item = reactiveFind(\"code\", code).singleResult(); // throws if missing\n\n// after\nOptional<Item> item = reactiveFind(\"code\", code).singleResultOptional().await().indefinitely();","handlingStrategy":"validation","validationCode":"long count = reactiveCount(\"code\", code).await().indefinitely();\nif (count != 1) {\n    throw new IllegalStateException(\"Expected exactly 1 item for code=\" + code + \", found \" + count);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return query.singleResult().await().indefinitely();\n} catch (PanacheQueryException e) {\n    // 0 or >1 matches; inspect count or fall back to firstResult\n    return null;\n}","preventionTips":["Use singleResultOptional() when zero matches is a normal case","Ensure a unique index backs every field used with singleResult()","Prefer firstResult() unless 'exactly one' is a real domain invariant"],"tags":["panache","mongodb","query-result","unique-constraint"],"backgroundTag":"unexpected-result-count","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"}