quarkusio/quarkus · error · UnableToParseMethodException

IgnoreCase cannot be specified for field${fieldInfo.name()}

Error message

IgnoreCase cannot be specified for field${fieldInfo.name()} because it is not a String type. Offending method is ${repositoryMethodDescription}.

What it means

IgnoreCase (or AllIgnoreCase) was specified in a derived query method for a field whose type is not String. Case-insensitive comparison only makes sense for textual fields, so the parser rejects it at build time with UnableToParseMethodException.

Source

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

                    if (relatedParentFieldInfo != null) {
                        joinClause = " LEFT JOIN " + topLevelFieldName + " " + childEntityAlias + " ON "
                                + entityAlias + "." + getIdFieldInfo(entityClass).name() + " = "
                                + topLevelFieldName + "." + relatedParentFieldInfo.name() + "."
                                + getIdFieldInfo(entityClass).name();
                    } else {
                        // Fallback for cases where the relationship is not explicit
                        joinClause = " LEFT JOIN " + entityAlias + "." + topLevelFieldName + " " + childEntityAlias;
                    }

                }
            } else {
                // Qualify simple field references with the entity alias to avoid JPQL ambiguity
                // when a field name matches the entity alias (e.g. field 'category' on entity 'Category')
                fieldName = entityAlias + "." + fieldName;
            }
            validateFieldWithOperation(operation, fieldInfo, fieldName, repositoryMethodDescription);
            if ((ignoreCase || allIgnoreCase) && !DotNames.STRING.equals(fieldInfo.type().name())) {
                throw new UnableToParseMethodException(
                        "IgnoreCase cannot be specified for field" + fieldInfo.name() + " because it is not a String type. "
                                + "Offending method is " + repositoryMethodDescription + ".");
            }

            if (where.length() > 0) {
                if (containsAnd && partsArray[i - 1].equals("And"))
                    where.append(" AND ");
                if (containsOr && partsArray[i - 1].equals("Or"))
                    where.append(" OR ");
            }

            String upperPrefix = (ignoreCase || allIgnoreCase) ? "UPPER(" : "";
            String upperSuffix = (ignoreCase || allIgnoreCase) ? ")" : "";

            where.append(upperPrefix).append(fieldName).append(upperSuffix);
            if ((operation == null) || "Equals".equals(operation) || "Is".equals(operation)) {
                paramsCount++;
                where.append(" = ").append(upperPrefix).append("?").append(paramsCount).append(upperSuffix);

View on GitHub (pinned to e1c734241f)

Solutions

Remove IgnoreCase/AllIgnoreCase from non-String fields in the method name
Convert the field to String if case-insensitive matching is genuinely required
Implement manual normalization: store a lowercased column and query findByLowercasedFieldEquals(...)

Example fix

// before (age is Integer)
List<User> findByAgeIgnoreCase(int age);
// after
List<User> findByAge(int age);

Defensive patterns

Strategy: validation

Validate before calling

// Only append IgnoreCase when the field is String:
// if (field.getType() == String.class) name += "IgnoreCase";

Try / catch

try {
    parser.parse(methodName);
} catch (UnableToParseMethodException e) {
    // drop IgnoreCase for non-String fields
    log.error("IgnoreCase misuse: " + e.getMessage());
}

Prevention

Only use IgnoreCase/AllIgnoreCase on String-typed conditions
Don't blanket-append IgnoreCase to all conditions in a method name
Keep a test that exercises every derived query method

When it happens

Trigger: Methods like findByAgeIgnoreCase(int age) or findAllByCreatedDateAllIgnoreCase() where the field type is Integer/Date/etc.; also triggered when a single field is marked IgnoreCase and the field's resolved type is not DotNames.STRING.

Common situations: Blindly appending IgnoreCase to every condition for 'safety' after migrating from a case-insensitive database; misunderstanding that IgnoreCase applies only to string comparisons.

Related errors

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