spring-projects/spring-framework · error · IllegalArgumentException

'targetListClass' must not be null

Error message

'targetListClass' must not be null

What it means

Thrown by ListFactoryBean.setTargetListClass() when it is explicitly invoked with null. The setter is annotated @Nullable yet guards against null because a null target list type is meaningless (ListFactoryBean defaults to java.util.ArrayList when the property is simply left unset). Spring's property binding calls the setter when the property is present in config, so this surfaces when a <property name="targetListClass"/> element resolves to null.

Solutions

1. Remove the <property name="targetListClass"/> element entirely; ListFactoryBean will default to ArrayList.
2. Provide a concrete List implementation, e.g. <property name="targetListClass" value="java.util.LinkedList"/>.
3. If the value comes from a placeholder, give it a non-null default, e.g. value="${list.type:java.util.ArrayList}".

Example fix

// before (broken)
ListFactoryBean fb = new ListFactoryBean();
fb.setSourceList(items);
fb.setTargetListClass(null);
// after
ListFactoryBean fb = new ListFactoryBean();
fb.setSourceList(items);
// simply omit setTargetListClass to use ArrayList

if (targetListClass == null) {
    // omit the call entirely instead of passing null
    return;
}
factoryBean.setTargetListClass(targetListClass);

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

try {
    fb.setTargetListClass(clazz);
} catch (IllegalArgumentException ex) {
    // clazz was null: fall back to default ArrayList by skipping the setter
    if (ex.getMessage().contains("must not be null")) return;
    throw ex;
}

When it happens

Trigger: An XML <property name="targetListClass"> that contains a null or empty value, or a parent/placeholder override that resolves the class name to null. Programmatic call factoryBean.setTargetListClass(null). Using a placeholder like ${list.type:} that resolves to an empty string bound to a Class argument.

Common situations: Overriding targetListClass via a properties/placeholder that is sometimes empty. Copy-pasting a ListFactoryBean bean definition and deleting the value but leaving the property element. Parent bean inheritance where the child clears the class to null.

Related errors

• 'targetMapClass' 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/4fae935cbe505c3e. Report an issue: GitHub.

Appendix: source

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

	/**
	 * Set the source List, typically populated via XML "list" elements.
	 */
	public void setSourceList(List<?> sourceList) {
		this.sourceList = sourceList;
	}

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


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

	@Override
	@SuppressWarnings("unchecked")
	protected List<Object> createInstance() {
		if (this.sourceList == null) {

View on GitHub (pinned to 69bf83ad71)