quarkusio/quarkus · error · UnableToParseMethodException

${operation} cannot be specified for field${fieldPath} becau

Error message

${operation} cannot be specified for field${fieldPath} because it is not a String type. Offending method is ${repositoryMethodDescription}.

What it means

A string-only derived query operation (Like, Contains, StartsWith, EndsWith, NotLike, etc. — STRING_LIKE_OPERATIONS) was applied to a field whose type is not String. The parser rejects this at build time with UnableToParseMethodException.

Source

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

            return false;
        }

        // Check if the operator is at the beginning or preceded by capital letter.
        boolean startsCorrectly = (index == 0) || Character.isLowerCase(str.charAt(index - 1));

        // Check if the operator ends before the end or is followed by a capital letter.
        boolean endsCorrectly = (index + operatorStr.length() == str.length())
                || Character.isUpperCase(str.charAt(index + operatorStr.length()));

        return startsCorrectly && endsCorrectly;

    }

    private void validateFieldWithOperation(String operation, FieldInfo fieldInfo, String fieldPath,
            String repositoryMethodDescription) {
        DotName fieldTypeDotName = fieldInfo.type().name();
        if (STRING_LIKE_OPERATIONS.contains(operation) && !DotNames.STRING.equals(fieldTypeDotName)) {
            throw new UnableToParseMethodException(
                    operation + " cannot be specified for field" + fieldPath + " because it is not a String type. "
                            + "Offending method is " + repositoryMethodDescription + ".");
        }

        if (BOOLEAN_OPERATIONS.contains(operation) && !DotNames.BOOLEAN.equals(fieldTypeDotName)
                && !DotNames.PRIMITIVE_BOOLEAN.equals(fieldTypeDotName)) {
            throw new UnableToParseMethodException(
                    operation + " cannot be specified for field" + fieldPath + " because it is not a boolean type. "
                            + "Offending method is " + repositoryMethodDescription + ".");
        }
    }

    private QueryType getType(String methodName) {
        if (methodName.startsWith("find") || methodName.startsWith("query") || methodName.startsWith("read")
                || methodName.startsWith("get")) {
            return QueryType.SELECT;
        }
        if (methodName.startsWith("count")) {

View on GitHub (pinned to e1c734241f)

Solutions

Use an equality/range operation appropriate to the field type instead of Like/Contains/StartsWith/EndsWith
Convert the field to String if pattern matching is genuinely needed
Cast or map the value in JPQL via @Query, e.g. CAST(age AS string) LIKE ...

Example fix

// before (age is Integer)
List<User> findByAgeLike(String pattern);
// after
List<User> findByAgeGreaterThan(int age);

Defensive patterns

Strategy: validation

Validate before calling

// Only use Like/Contains/StartsWith/EndsWith on String fields:
// if (String.class != field.getType()) throw new IllegalArgumentException("String op on non-String field");

Try / catch

try {
    parser.parse(methodName);
} catch (UnableToParseMethodException e) {
    // switch to a type-appropriate operator or use @Query with CAST
    throw new IllegalStateException("String-only op misuse: " + e.getMessage());
}

Prevention

Reserve Like/Contains/StartsWith/EndsWith for String fields only
Re-check derived queries after changing a field's type in the entity
Prefer equality/range operations for numeric and date fields

When it happens

Trigger: Methods like findByAgeLike(String pattern), findByNameContains on a numeric/date/binary field; any operation in STRING_LIKE_OPERATIONS whose resolved FieldInfo type is not DotNames.STRING.

Common situations: Pattern-matching queries written against numeric columns; copy-pasting string query method patterns to non-string fields; schema type changes from String to numeric after migration.

Related errors

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