{"record":{"id":"376cd8d5a48ea4d5","repo":"spring-projects/spring-framework","slug":"targetlistclass-must-implement-java-util-list","errorCode":null,"errorMessage":"'targetListClass' must implement [java.util.List]","messagePattern":"'targetListClass' must implement \\[java\\.util\\.List\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-beans/src/main/java/org/springframework/beans/factory/config/ListFactoryBean.java","lineNumber":64,"sourceCode":"\t * Set the source List, typically populated via XML \"list\" elements.\n\t */\n\tpublic void setSourceList(List<?> sourceList) {\n\t\tthis.sourceList = sourceList;\n\t}\n\n\t/**\n\t * Set the class to use for the target List. Can be populated with a fully\n\t * qualified class name when defined in a Spring application context.\n\t * <p>Default is a {@code java.util.ArrayList}.\n\t * @see java.util.ArrayList\n\t */\n\t@SuppressWarnings(\"rawtypes\")\n\tpublic void setTargetListClass(@Nullable Class<? extends List> targetListClass) {\n\t\tif (targetListClass == null) {\n\t\t\tthrow new IllegalArgumentException(\"'targetListClass' must not be null\");\n\t\t}\n\t\tif (!List.class.isAssignableFrom(targetListClass)) {\n\t\t\tthrow new IllegalArgumentException(\"'targetListClass' must implement [java.util.List]\");\n\t\t}\n\t\tthis.targetListClass = targetListClass;\n\t}\n\n\n\t@Override\n\t@SuppressWarnings(\"rawtypes\")\n\tpublic Class<List> getObjectType() {\n\t\treturn List.class;\n\t}\n\n\t@Override\n\t@SuppressWarnings(\"unchecked\")\n\tprotected List<Object> createInstance() {\n\t\tif (this.sourceList == null) {\n\t\t\tthrow new IllegalArgumentException(\"'sourceList' is required\");\n\t\t}\n\t\tList<Object> result = null;","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/spring-projects/spring-framework/blob/69bf83ad716d0cfc4b0520a19b4d8b24c79d1538/spring-beans/src/main/java/org/springframework/beans/factory/config/ListFactoryBean.java#L46-L82","documentation":"Thrown by ListFactoryBean.setTargetListClass() when the supplied Class does not implement java.util.List (checked via List.class.isAssignableFrom). ListFactoryBean must instantiate the class to hold the list elements, so it requires a concrete List type. This is a type-safety guard so the BeanUtils.instantiateClass call later cannot fail with a ClassCastException.","triggerScenarios":"Passing a Set type (java.util.HashSet), a Queue, a Map, or any arbitrary class to setTargetListClass. XML config like <property name=\"targetListClass\" value=\"java.util.HashSet\"/>. Passing an abstract List type or one with no no-arg constructor also surfaces nearby (during instantiation, not here).","commonSituations":"Confusing ListFactoryBean with SetFactoryBean and pointing it at a Set. Copy-pasting a MapFactoryBean/MapFactoryBean definition into a ListFactoryBean and forgetting to change the class. Specifying a custom collection that extends Collection but not List.","solutions":["Change targetListClass to a concrete java.util.List implementation such as java.util.ArrayList, java.util.LinkedList, or java.util.concurrent.CopyOnWriteArrayList.","If you actually want a Set, switch to org.springframework.beans.factory.config.SetFactoryBean instead.","Verify the class has a public no-arg constructor (BeanUtils.instantiateClass needs one)."],"exampleFix":"// before (broken)\nfb.setTargetListClass(java.util.HashSet.class); // not a List\n// after\nfb.setTargetListClass(java.util.LinkedList.class);","handlingStrategy":"type-guard","validationCode":"Class<?> c = /* from config */;\nif (c != null && !List.class.isAssignableFrom(c)) {\n    throw new IllegalStateException(c.getName() + \" is not a java.util.List\");\n}\nfb.setTargetListClass((Class<? extends List>) c);","typeGuard":"static boolean isConcreteList(Class<?> c) {\n    return c != null && List.class.isAssignableFrom(c)\n        && !Modifier.isAbstract(c.getModifiers()) && !c.isInterface();\n}","tryCatchPattern":"try {\n    fb.setTargetListClass(clazz);\n} catch (IllegalArgumentException ex) {\n    if (ex.getMessage().contains(\"must implement\")) {\n        // wrong collection type: log and use a SetFactoryBean instead, or switch to ArrayList\n    }\n    throw ex;\n}","preventionTips":["Keep a whitelist of allowed list classes (ArrayList, LinkedList, CopyOnWriteArrayList).","Use SetFactoryBean for Set types and MapFactoryBean for Map types - don't mix them.","Validate config classes in a startup self-check before the context refreshes."],"tags":["spring","factory-bean","collection","type-check","configuration"],"backgroundTag":null,"analyzedSha":"69bf83ad716d0cfc4b0520a19b4d8b24c79d1538","analyzedAt":"2026-08-09T15:32:58.770Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}