spring-projects/spring-framework · error · IllegalArgumentException

'targetMapClass' must not be null

Error message

'targetMapClass' must not be null

What it means

Thrown by MapFactoryBean.setTargetMapClass() when explicitly passed null. Mirror of ListFactoryBean's guard: MapFactoryBean defaults to a LinkedHashMap when the property is unset, so an explicit null is a configuration mistake rather than a meaningful value. The setter is invoked by Spring's property binding whenever the property element is present.

Solutions

1. Delete the <property name="targetMapClass"/> element to fall back to LinkedHashMap.
2. Supply a concrete Map type, e.g. value="java.util.concurrent.ConcurrentHashMap".
3. Give the placeholder a non-null default: value="${map.type:java.util.LinkedHashMap}".

Example fix

// before (broken)
MapFactoryBean fb = new MapFactoryBean();
fb.setSourceMap(map);
fb.setTargetMapClass(null);
// after
MapFactoryBean fb = new MapFactoryBean();
fb.setSourceMap(map);
// omit setTargetMapClass for LinkedHashMap

if (targetMapClass == null) {
    return; // omit the setter to use LinkedHashMap default
}
factoryBean.setTargetMapClass(targetMapClass);

static boolean isValidMapClass(Class<?> c) {
    return c != null && Map.class.isAssignableFrom(c);
}

try {
    fb.setTargetMapClass(clazz);
} catch (IllegalArgumentException ex) {
    if (ex.getMessage().contains("must not be null")) return;
    throw ex;
}

When it happens

Trigger: XML <property name="targetMapClass"> resolving to null (empty element or placeholder that yields null). Programmatic call mapFactoryBean.setTargetMapClass(null). A parent-bean override that clears the value.

Common situations: Placeholder such as value="${map.type:}" resolving to empty and bound to Class. Removing a targetMapClass value but leaving the property element. Bean inheritance clearing the property in a child.

Related errors

• 'targetListClass' must not be null
• 'sourceList' is required
• 'sourceMap' is required
• 'targetListClass' must implement [java.util.List]
• 'targetMapClass' must implement [java.util.Map]

AI-assisted analysis of spring-projects/spring-framework@69bf83ad71 (2026-08-09). Data as JSON: /api/errors/317ec6ed7dc64d5d. Report an issue: GitHub.

Appendix: source

Thrown at spring-beans/src/main/java/org/springframework/beans/factory/config/MapFactoryBean.java:61

	/**
	 * Set the source Map, typically populated via XML "map" elements.
	 */
	public void setSourceMap(Map<?, ?> sourceMap) {
		this.sourceMap = sourceMap;
	}

	/**
	 * Set the class to use for the target Map. Can be populated with a fully
	 * qualified class name when defined in a Spring application context.
	 * <p>Default is a linked HashMap, keeping the registration order.
	 * @see java.util.LinkedHashMap
	 */
	@SuppressWarnings("rawtypes")
	public void setTargetMapClass(@Nullable Class<? extends Map> targetMapClass) {
		if (targetMapClass == null) {
			throw new IllegalArgumentException("'targetMapClass' must not be null");
		}
		if (!Map.class.isAssignableFrom(targetMapClass)) {
			throw new IllegalArgumentException("'targetMapClass' must implement [java.util.Map]");
		}
		this.targetMapClass = targetMapClass;
	}


	@Override
	@SuppressWarnings("rawtypes")
	public Class<Map> getObjectType() {
		return Map.class;
	}

	@Override
	@SuppressWarnings("unchecked")
	protected Map<Object, Object> createInstance() {
		if (this.sourceMap == null) {

View on GitHub (pinned to 69bf83ad71)