quarkusio/quarkus · error · IllegalArgumentException

YamlListObjectHandler can only be used for fields / methods

Error message

YamlListObjectHandler can only be used for fields / methods that are of type 'List<SomeClass>' where 'SomeClass' is an application class

What it means

validateType only accepts parameterized types named java.util.List; the handler exists solely to bind YAML lists of objects. Any other kind (raw type, array, Map, Optional...) is rejected with IllegalArgumentException.

Source

Thrown at extensions/spring-boot-properties/deployment/src/main/java/io/quarkus/spring/boot/properties/deployment/YamlListObjectHandler.java:219

            throw new IllegalArgumentException(
                    "The use of interfaces as the generic type of Lists fields / methods is not allowed. Offending field is '"
                            + member.name() + "' of class '" + member.declaringClass().name().toString() + "'");
        }
        if (!classInfo.hasNoArgsConstructor()) {
            throw new IllegalArgumentException(
                    String.format("Class '%s' which is used as %s in class '%s' must have a no-args constructor", classInfo,
                            member.phraseUsage(), member.declaringClass().name().toString()));
        }
        if (!Modifier.isPublic(classInfo.flags())) {
            throw new IllegalArgumentException(
                    String.format("Class '%s' which is used as %s in class '%s' must be a public class", classInfo,
                            member.phraseUsage(), member.declaringClass().name().toString()));
        }
    }

    private ClassInfo validateType(Type type) {
        if (type.kind() != Type.Kind.PARAMETERIZED_TYPE) {
            throw new IllegalArgumentException(ILLEGAL_ARGUMENT_MESSAGE);
        }
        ParameterizedType parameterizedType = (ParameterizedType) type;
        if (!DotNames.LIST.equals(parameterizedType.name())) {
            throw new IllegalArgumentException(ILLEGAL_ARGUMENT_MESSAGE);
        }
        if (parameterizedType.arguments().size() != 1) {
            throw new IllegalArgumentException(ILLEGAL_ARGUMENT_MESSAGE);
        }
        ClassInfo classInfo = index.getClassByName(parameterizedType.arguments().get(0).name());
        if (classInfo == null) {
            throw new IllegalArgumentException(ILLEGAL_ARGUMENT_MESSAGE);
        }
        return classInfo;
    }

    /**
     * An abstraction over Field and Method which we will use in order to keep the same code for Class and Interface cases
     */

View on GitHub (pinned to e1c734241f)

Solutions

  1. Change the member type to List<SomeClass> with an explicit type argument
  2. Use Set<SomeClass>/Map only via @ConfigMapping in quarkus-config-yaml, not via @ConfigProperties class processing
  3. Flatten the structure to supported List-of-object shape

Example fix

// before
Set<ServerConfig> servers();
// after
List<ServerConfig> servers();
Defensive patterns

Strategy: type-guard

Validate before calling

static void requireListMember(Field f) {
    if (!(f.getGenericType() instanceof ParameterizedType p) || p.getRawType() != List.class)
        throw new IllegalStateException(f + " must be List<SomeClass>");
}

Type guard

boolean isListOfObjects(Type t) {
    return t instanceof ParameterizedType p && p.getRawType() == List.class && p.getActualTypeArguments().length == 1;
}

Try / catch

catch (IllegalArgumentException e) { if (e.getMessage().contains("List<SomeClass>")) { /* change member type to List<...> */ } throw e; }

Prevention

When it happens

Trigger: YamlListObjectHandler.handle is invoked for a member whose type is not a PARAMETERIZED_TYPE (e.g. raw List without type argument, or Set/Map of objects) — typically reached when list-of-object support is misapplied to a non-List member.

Common situations: Using Set<SomeClass> or Map<String,SomeClass> for nested config objects and expecting the YAML list handler to support it; raw List fields.

Related errors

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