{"record":{"id":"0de2d454adb56e03","repo":"spring-projects/spring-framework","slug":"targetmapclass-must-implement-java-util-map","errorCode":null,"errorMessage":"'targetMapClass' must implement [java.util.Map]","messagePattern":"'targetMapClass' must implement \\[java\\.util\\.Map\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-beans/src/main/java/org/springframework/beans/factory/config/MapFactoryBean.java","lineNumber":64,"sourceCode":"\t * Set the source Map, typically populated via XML \"map\" elements.\n\t */\n\tpublic void setSourceMap(Map<?, ?> sourceMap) {\n\t\tthis.sourceMap = sourceMap;\n\t}\n\n\t/**\n\t * Set the class to use for the target Map. Can be populated with a fully\n\t * qualified class name when defined in a Spring application context.\n\t * <p>Default is a linked HashMap, keeping the registration order.\n\t * @see java.util.LinkedHashMap\n\t */\n\t@SuppressWarnings(\"rawtypes\")\n\tpublic void setTargetMapClass(@Nullable Class<? extends Map> targetMapClass) {\n\t\tif (targetMapClass == null) {\n\t\t\tthrow new IllegalArgumentException(\"'targetMapClass' must not be null\");\n\t\t}\n\t\tif (!Map.class.isAssignableFrom(targetMapClass)) {\n\t\t\tthrow new IllegalArgumentException(\"'targetMapClass' must implement [java.util.Map]\");\n\t\t}\n\t\tthis.targetMapClass = targetMapClass;\n\t}\n\n\n\t@Override\n\t@SuppressWarnings(\"rawtypes\")\n\tpublic Class<Map> getObjectType() {\n\t\treturn Map.class;\n\t}\n\n\t@Override\n\t@SuppressWarnings(\"unchecked\")\n\tprotected Map<Object, Object> createInstance() {\n\t\tif (this.sourceMap == null) {\n\t\t\tthrow new IllegalArgumentException(\"'sourceMap' is required\");\n\t\t}\n\t\tMap<Object, 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/MapFactoryBean.java#L46-L82","documentation":"Thrown by MapFactoryBean.setTargetMapClass() when the supplied Class does not implement java.util.Map (checked via Map.class.isAssignableFrom). MapFactoryBean instantiates this class to hold the source map entries, so the type must be a real Map. The guard prevents a later ClassCastException during instantiation and element conversion.","triggerScenarios":"Passing a List, Set, Properties-less custom type, or arbitrary class to setTargetMapClass. XML like <property name=\"targetMapClass\" value=\"java.util.ArrayList\"/>. Note: java.util.Properties DOES implement Map and is accepted.","commonSituations":"Mixing up MapFactoryBean and ListFactoryBean/SetFactoryBean. Pointing at a custom non-Map collection. Providing an interface or abstract Map type with no no-arg constructor (caught later as a BeanInstantiationException, but worth checking).","solutions":["Set targetMapClass to a concrete java.util.Map implementation such as java.util.HashMap, java.util.TreeMap, java.util.LinkedHashMap, or java.util.concurrent.ConcurrentHashMap.","Ensure the class has a public no-arg constructor.","If you wanted a list/set, switch to ListFactoryBean / SetFactoryBean."],"exampleFix":"// before (broken)\nfb.setTargetMapClass(java.util.HashSet.class); // not a Map\n// after\nfb.setTargetMapClass(java.util.TreeMap.class);","handlingStrategy":"type-guard","validationCode":"Class<?> c = /* from config */;\nif (c != null && !Map.class.isAssignableFrom(c)) {\n    throw new IllegalStateException(c.getName() + \" is not a java.util.Map\");\n}\nfb.setTargetMapClass((Class<? extends Map>) c);","typeGuard":"static boolean isConcreteMap(Class<?> c) {\n    return c != null && Map.class.isAssignableFrom(c)\n        && !Modifier.isAbstract(c.getModifiers()) && !c.isInterface();\n}","tryCatchPattern":"try {\n    fb.setTargetMapClass(clazz);\n} catch (IllegalArgumentException ex) {\n    if (ex.getMessage().contains(\"must implement\")) {\n        // switch to the correct factory bean or use a concrete Map class\n    }\n    throw ex;\n}","preventionTips":["Whitelist allowed map classes (HashMap, LinkedHashMap, TreeMap, ConcurrentHashMap).","Use ListFactoryBean/SetFactoryBean for non-Map collections.","Confirm a public no-arg constructor exists so instantiation succeeds later."],"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"}