quarkusio/quarkus · error · IllegalArgumentException

${method} of Repository ${repository} is meant to be an exis

Error message

${method} of Repository ${repository} is meant to be an exists query and can therefore only have a boolean return type

What it means

Derived methods named existsBy... are generated as existence checks whose only meaningful result is a boolean. The spring-data-jpa extension requires the return type to be boolean or java.lang.Boolean; any other return type fails the build with this IllegalArgumentException.

Source

Thrown at extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/generate/DerivedMethodsAdder.java:317

                            throw new IllegalArgumentException(
                                    method.name() + " of Repository " + repositoryClassInfo
                                            + " is meant to be a count query and therefore doesn't " +
                                            "support Pageable and Sort method parameters");
                        }

                        // call JpaOperations.count()
                        Expr count = bc.invokeVirtual(
                                MethodDesc.of(AbstractManagedJpaOperations.class, "count", long.class,
                                        Class.class, String.class, Object[].class),
                                ops, entityClass,
                                Const.of(parseResult.getQuery()), paramsArray);

                        handleLongReturnValue(bc, count, returnType.name());

                    } else if (parseResult.getQueryType() == MethodNameParser.QueryType.EXISTS) {
                        if (!DotNames.PRIMITIVE_BOOLEAN.equals(returnType.name())
                                && !DotNames.BOOLEAN.equals(returnType.name())) {
                            throw new IllegalArgumentException(
                                    method.name() + " of Repository " + repositoryClassInfo
                                            + " is meant to be an exists query and can therefore only have a boolean return type");
                        }
                        if ((finalSortParameterIndex != null) || finalPageableParameterIndex != null) {
                            throw new IllegalArgumentException(
                                    method.name() + " of Repository " + repositoryClassInfo
                                            + " is meant to be a count query and therefore doesn't " +
                                            "support Pageable and Sort method parameters");
                        }

                        // call JpaOperations.exists()
                        Expr exists = bc.invokeVirtual(
                                MethodDesc.of(AbstractManagedJpaOperations.class, "exists", boolean.class,
                                        Class.class, String.class, Object[].class),
                                ops, entityClass,
                                Const.of(parseResult.getQuery()), paramsArray);

                        handleBooleanReturnValue(bc, exists, returnType.name());

View on GitHub (pinned to e1c734241f)

Solutions

Change the return type to primitive boolean
Or use java.lang.Boolean when a boxed type is needed
If a different shape is required, use @Query with an appropriate select instead of the existsBy prefix

Example fix

// before
int existsByEmail(String email);

// after
boolean existsByEmail(String email);

Defensive patterns

Strategy: validation

Validate before calling

// Ensure every existsBy method returns boolean or Boolean
for (Method m : PersonRepository.class.getDeclaredMethods()) {
    if (m.getName().startsWith("existsBy")) {
        Class<?> r = m.getReturnType();
        if (r != boolean.class && r != Boolean.class)
            throw new IllegalStateException(m.getName() + " must return boolean/Boolean, got " + r);
    }
}

Prevention

Always declare existsBy methods as returning primitive boolean
Do not map SQL-style 0/1 ints into repository signatures
Use Optional<T> only for findBy, never for existsBy

When it happens

Trigger: Declaring e.g. int existsByEmail(String email) or Long existsById(Long id) — an EXISTS query type whose returnType.name() is neither DotNames.PRIMITIVE_BOOLEAN nor DotNames.BOOLEAN.

Common situations: Mapping boolean results to int 0/1 out of habit from SQL or another ORM; reusing a find method's signature after renaming it to existsBy; Optional-based return types mistakenly used for existence checks.

Related errors

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