quarkusio/quarkus · error · UnableToParseMethodException

Distinct is not yet supported. Offending method is ${reposit

Error message

Distinct is not yet supported. Offending method is ${repositoryMethodDescription}.

What it means

Quarkus Spring Data JPA's derived query parser rejects repository method names containing the 'Distinct' keyword because distinct projection is not implemented in the method-name-to-JPQL translation. The build fails at augmentation time with UnableToParseMethodException naming the offending method.

Source

Thrown at extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/MethodNameParser.java:132

                                + repositoryMethodDescription + ".");
            }
            try {
                String topCountStr = methodName.substring(minFirstOrTopIndex, byIndex)
                        .replace("Top", "").replace("First", "");
                if (topCountStr.isEmpty()) {
                    topCount = 1;
                } else {
                    topCount = Integer.valueOf(topCountStr);
                }
            } catch (Exception e) {
                throw new UnableToParseMethodException(
                        "Unable to parse query with limiting results clause. Offending method is "
                                + repositoryMethodDescription + ".");
            }
        }

        if (methodName.substring(0, byIndex).contains("Distinct")) {
            throw new UnableToParseMethodException(
                    "Distinct is not yet supported. Offending method is " + repositoryMethodDescription + ".");
        }

        // handle 'AllIgnoreCase'
        String afterByPart = methodName.substring(byIndex + 2);
        boolean allIgnoreCase = false;
        if (afterByPart.contains(ALL_IGNORE_CASE)) {
            allIgnoreCase = true;
            afterByPart = afterByPart.replace(ALL_IGNORE_CASE, "");
        }

        // handle the 'OrderBy' clause which is assumed to be at the end of the query
        Sort sort = null;
        if (containsLogicOperator(afterByPart, ORDER_BY)) {
            int orderByIndex = afterByPart.indexOf(ORDER_BY);
            if (orderByIndex + ORDER_BY.length() == afterByPart.length()) {
                throw new UnableToParseMethodException(
                        "A field must by supplied after 'OrderBy' . Offending method is " + repositoryMethodDescription + ".");

View on GitHub (pinned to e1c734241f)

Solutions

Remove 'Distinct' from the method name and use a @Query annotation with 'SELECT DISTINCT ...' in JPQL instead
Restructure the query so duplicates cannot occur (e.g. query the parent entity only, or use a DTO projection via @Query)
If dedup is only needed for existence checks, use exists...By or a returning-limiting variant without Distinct

Example fix

// before
List<User> findDistinctByEmailByLastname(String lastname);
// after
@Query("SELECT DISTINCT u.email FROM User u WHERE u.lastname = :ln")
List<String> findEmailsByLastname(@Param("ln") String lastname);

Defensive patterns

Strategy: validation

Validate before calling

// before compiling, grep your repositories:
// grep -rnE 'findDistinct|countDistinct|readDistinct|getDistinct|deleteDistinct' src/main/java

Try / catch

// Build-time failure; catch during tests:
try {
    // augmentation happens at build; instead validate in a unit test
    // by invoking the parser on the method name
    parser.parse(methodName);
} catch (UnableToParseMethodException e) {
    throw new IllegalStateException("Use @Query for Distinct: " + e.getMessage());
}

Prevention

Avoid 'Distinct' in derived method names; prefer explicit @Query JPQL
Search the codebase for 'Distinct' in repository interfaces when migrating to Quarkus
Write a build/CI test that instantiates all repositories (QuarkusTest) to catch parse failures early

When it happens

Trigger: Declaring a derived repository method whose name contains 'Distinct' between the query prefix and 'By' (e.g. findDistinctByEmailByLastname(String lastname), countDistinctUsersBy...) on a Spring Data JPA repository processed by Quarkus.

Common situations: Porting a Spring Boot app to Quarkus where derived queries used Distinct to deduplicate joined or one-to-many results; copying Spring Data query method names verbatim.

Related errors

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