quarkusio/quarkus · error · UnableToParseMethodException

fieldNotResolvableMessage + detail + offendingMethodMessage

Error message

fieldNotResolvableMessage + detail + offendingMethodMessage

What it means

A field path in a derived query method could not be resolved against the entity: either the first segment does not match any entity field, or (when the path is nested) the failing segment is reported with detail 'Can not resolve <ParentClass>.<segment>'. Throws UnableToParseMethodException at build time.

Source

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

            int firstSeparator = fieldPathExpression.indexOf('_', fieldStartIndex);
            int fieldEndIndex = firstSeparator == -1 ? fieldPathExpression.length() : firstSeparator;
            while (fieldEndIndex >= fieldStartIndex) {
                String fieldName = fieldPathExpression.substring(fieldStartIndex, fieldEndIndex);
                String simpleFieldName = lowerFirstLetter(fieldName);
                fieldInfo = getFieldInfo(simpleFieldName, parentFieldInfo == null ? parentClassInfo : parentFieldInfo,
                        parentSuperClassInfos);
                if (fieldInfo != null) {
                    break;
                }
                fieldEndIndex = previousPotentialFieldEnd(fieldPathExpression, fieldStartIndex, fieldEndIndex);
            }
            if (fieldInfo == null) {
                String detail = "";
                if (fieldStartIndex > 0) {
                    String notMatched = lowerFirstLetter(fieldPathExpression.substring(fieldStartIndex));
                    detail = "Can not resolve " + parentClassInfo + "." + notMatched + ". ";
                }
                throw new UnableToParseMethodException(
                        fieldNotResolvableMessage + detail + offendingMethodMessage);
            }
            if (fieldPathBuilder.length() > 0) {
                fieldPathBuilder.append('.');
            }
            fieldPathBuilder.append(fieldInfo.name());
            if (!isHibernateProvidedBasicType(fieldInfo.type().name())) {
                DotName parentClassName;
                boolean typed = false;
                if (fieldInfo.type().kind() == Type.Kind.TYPE_VARIABLE) {
                    typed = true;
                    parentClassName = getParentNameFromTypedFieldViaHierarchy(fieldInfo, mappedSuperClassInfos);
                } else if (fieldInfo.type().kind() == Type.Kind.PARAMETERIZED_TYPE) {
                    parentClassName = fieldInfo.type().asParameterizedType().arguments().stream().findFirst().get().name();
                } else {
                    parentClassName = fieldInfo.type().name();
                }
                parentClassInfo = indexView.getClassByName(parentClassName);

View on GitHub (pinned to e1c734241f)

Solutions

Correct the field name in the method to match the entity's Java property exactly (lowerFirstLetter applies)
For nested paths use underscore separators with real property names at every level: findByAddress_City(...)
If the field truly does not exist, add it to the entity or use @Query with explicit JPQL

Example fix

// before (entity User has 'email', not 'mail')
List<User> findByMail(String mail);
// after
List<User> findByEmail(String mail);

Defensive patterns

Strategy: validation

Validate before calling

// Verify each path segment against entity properties:
// boolean ok = Arrays.stream(Entity.class.getDeclaredFields()).anyMatch(f -> f.getName().equals(fieldName));

Try / catch

try {
    parser.parse(methodName);
} catch (UnableToParseMethodException e) {
    // e.getMessage() names the unresolvable parent.field — fix or replace with @Query
    throw new IllegalStateException("Unresolvable field: " + e.getMessage());
}

Prevention

Use IDE rename refactoring so entity field renames propagate to derived methods
Use Java property names (camelCase), never SQL column names
Cover every repository method with a test that boots the application

When it happens

Trigger: findByFieldname(...) where 'fieldname' is not a property of the entity; nested paths like findByAddress_Zip(...) where Address has no 'zip' property; wrong casing of the first letter after parsing.

Common situations: Renamed or removed entity fields; typos; using DB column names instead of Java field names; referencing properties of a related entity that no longer exist after a schema change.

Related errors

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