quarkusio/quarkus · error · IllegalArgumentException

'value' attribute must be specified on @Query annotation of

Error message

'value' attribute must be specified on @Query annotation of method. Offending method is ${method} of Repository ${repository}

What it means

@Query requires its 'value' attribute to be present so the extension knows what query to generate. When the annotation instance has no 'value' set (only other attributes or empty), CustomQueryMethodsAdder.verifyQueryAnnotation throws this error at build time because there is no query string to compile into the method body.

Source

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

        Set<String> namedParameters = new LinkedHashSet<>();
        final Matcher matcher = NAMED_PARAMETER.matcher(queryString);
        while (matcher.find()) {
            namedParameters.add(matcher.group(1));
        }
        return namedParameters;
    }

    // we currently only support the 'value' attribute of @Query
    private void verifyQueryAnnotation(AnnotationInstance queryInstance, String methodName, String repositoryName) {
        List<AnnotationValue> values = queryInstance.values();
        for (AnnotationValue value : values) {
            if (!QUERY_VALUE_FIELD.equals(value.name()) && !QUERY_COUNT_FIELD.equals(value.name())) {
                throw new IllegalArgumentException("Attribute " + value.name() + " of @Query is currently not supported. " +
                        "Offending method is " + methodName + " of Repository " + repositoryName);
            }
        }
        if (queryInstance.value(QUERY_VALUE_FIELD) == null) {
            throw new IllegalArgumentException("'value' attribute must be specified on @Query annotation of method. " +
                    "Offending method is " + methodName + " of Repository " + repositoryName);
        }
    }

    private Expr generateParamsArray(List<Integer> queryParameterIndexes, BlockCreator bc, ParamVar[] params) {
        LocalVar paramsArray = bc.localVar("paramsArray", bc.newEmptyArray(Object.class, queryParameterIndexes.size()));
        for (int i = 0; i < queryParameterIndexes.size(); i++) {
            bc.set(paramsArray.elem(i), params[queryParameterIndexes.get(i)]);
        }
        return paramsArray;
    }

    private Expr generateParametersObject(Map<String, Integer> namedParameterToIndex, BlockCreator bc, ParamVar[] params) {
        LocalVar parameters = bc.localVar("parameters", bc.new_(ClassDesc.of(Parameters.class.getName())));
        for (Map.Entry<String, Integer> entry : namedParameterToIndex.entrySet().stream()
                .sorted(Map.Entry.comparingByKey()).toList()) {
            bc.invokeVirtual(
                    MethodDesc.of(Parameters.class, "and", Parameters.class,

View on GitHub (pinned to e1c734241f)

Solutions

Provide the JPQL string in the 'value' attribute of @Query
If the method should be derived from its name, remove @Query entirely and let method-name parsing generate the query
Remove the method if it is unused/accidental
Move the query to a custom repository fragment implementation if it needs dynamic construction

Example fix

// before
@Query
List<User> findActive();

// after
@Query("SELECT u FROM User u WHERE u.active = true")
List<User> findActive();

Defensive patterns

Strategy: validation

Validate before calling

boolean ok = q != null && !q.value().isBlank();

Prevention

Never commit @Query without a value
Remove placeholder empty @Query annotations before merging
Let derived method names generate queries instead of empty @Query

When it happens

Trigger: Declaring @Query on a repository method without supplying the query string, e.g. @Query("") handled as missing or @Query(countName = "...") only, detected in verifyQueryAnnotation when queryInstance.value(QUERY_VALUE_FIELD) is null.

Common situations: Leaving the query empty as a TODO; using only named-query attributes like name/countName copied from Spring; IDE template generating @Query() without value.

Related errors

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