quarkusio/quarkus · error · IllegalArgumentException

Unsupported query type in @Query. Offending method is ${meth

Error message

Unsupported query type in @Query. Offending method is ${methodName} of Repository ${repositoryName}

What it means

The @Query string must start with select/from/delete/update (case-insensitive) so Quarkus can classify it as a read or modifying query. Anything else (e.g. native SQL comments, WITH clauses for CTEs, or misspelled keywords) cannot be handled and fails the build with this IllegalArgumentException.

Source

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

                verifyQueryAnnotation(queryInstance, methodName, repositoryName);
                queryString = queryInstance.value(QUERY_VALUE_FIELD).asString().trim();
            } else if (namedQueryInstance != null) {
                queryString = namedQueryInstance.value(NAMED_QUERY_FIELD).asString().trim();
            } else {
                // handled by DerivedMethodsAdder
                continue;
            }

            if (queryString.contains("#{")) {
                throw new IllegalArgumentException("spEL expressions are not currently supported. " +
                        "Offending method is " + methodName + " of Repository " + repositoryName);
            }

            if (!(queryString.startsWith("select") || queryString.startsWith("SELECT")
                    || queryString.startsWith("from") || queryString.startsWith("FROM")
                    || queryString.startsWith("delete") || queryString.startsWith("DELETE")
                    || queryString.startsWith("update") || queryString.startsWith("UPDATE"))) {
                throw new IllegalArgumentException("Unsupported query type in @Query. " +
                        "Offending method is " + methodName + " of Repository " + repositoryName);
            }

            List<Type> methodParameterTypes = method.parameterTypes();
            String[] methodParameterTypesStr = new String[methodParameterTypes.size()];
            List<Integer> queryParameterIndexes = new ArrayList<>(methodParameterTypes.size());
            Integer pageableParameterIndex = null;
            Integer sortParameterIndex = null;
            for (int i = 0; i < methodParameterTypes.size(); i++) {
                DotName parameterType = methodParameterTypes.get(i).name();
                methodParameterTypesStr[i] = parameterType.toString();
                if (DotNames.SPRING_DATA_PAGEABLE.equals(parameterType)
                        || DotNames.SPRING_DATA_PAGE_REQUEST.equals(parameterType)) {
                    if (pageableParameterIndex != null) {
                        throw new IllegalArgumentException("Method " + method.name() + " of Repository " + repositoryClassInfo
                                + "has invalid parameters - only a single parameter of type" + DotNames.SPRING_DATA_PAGEABLE
                                + " can be specified");
                    }

View on GitHub (pinned to e1c734241f)

Solutions

Ensure the query string literally starts with SELECT/FROM/DELETE/UPDATE (case-insensitive) with no leading whitespace or comments
Move CTE (WITH ...) queries into a named stored procedure or restructure to avoid the WITH clause
Strip SQL comments from the @Query value
Log/print the annotation value if unsure what the string actually starts with

Example fix

// before
@Query("-- active users\nselect u from User u where u.active = true")
// after
@Query("select u from User u where u.active = true")

Defensive patterns

Strategy: validation

Validate before calling

String q = query == null ? "" : query.trim();
boolean ok = q.matches("(?i)^(select|from|delete|update).*");
if (!ok) throw new IllegalArgumentException("@Query must start with select/from/delete/update: " + q);

Try / catch

try {
    compile();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unsupported query type in @Query")) {
        log.error("Inspect the first characters of the @Query string");
    }
    throw e;
}

Prevention

Ensure no leading whitespace, newlines, or SQL comments in @Query
Avoid WITH/CTE clauses in @Query on Quarkus
Check for typos in the leading keyword
Keep queries on a single line starting with the verb

When it happens

Trigger: @Query whose value starts with something other than select/from/delete/update: leading whitespace or newline, a SQL comment (-- or /*), a CTE like WITH ..., a misspelled keyword (e.g. 'SELEC'), or an empty string with only a nativeQuery.

Common situations: Multi-line query strings where the first line is a comment; CTE queries (WITH temp AS (...)) ported from SQL; queries with leading blank lines or indentation from code formatting; using nativeQuery=true with vendor-specific prefixes.

Related errors

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