spring-projects/spring-framework · error · IllegalArgumentException

Mapped value [{}] for scope key [{}] is not an instance of r

Error message

Mapped value [{}] for scope key [{}] is not an instance of required type [{}] or a corresponding Class or String value indicating a Scope implementation

What it means

CustomScopeConfigurer.postProcessBeanFactory iterates the scopes map and accepts only Scope instances, Class objects (assignable to Scope), or String class names. Any other type for a scope value throws IllegalArgumentException, because the configurer cannot turn it into a Scope registration.

Source

Thrown at spring-beans/src/main/java/org/springframework/beans/factory/config/CustomScopeConfigurer.java:113

	@Override
	public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
		if (this.scopes != null) {
			this.scopes.forEach((scopeKey, value) -> {
				if (value instanceof Scope scope) {
					beanFactory.registerScope(scopeKey, scope);
				}
				else if (value instanceof Class<?> scopeClass) {
					Assert.isAssignable(Scope.class, scopeClass, "Invalid scope class");
					beanFactory.registerScope(scopeKey, (Scope) BeanUtils.instantiateClass(scopeClass));
				}
				else if (value instanceof String scopeClassName) {
					Class<?> scopeClass = ClassUtils.resolveClassName(scopeClassName, this.beanClassLoader);
					Assert.isAssignable(Scope.class, scopeClass, "Invalid scope class");
					beanFactory.registerScope(scopeKey, (Scope) BeanUtils.instantiateClass(scopeClass));
				}
				else {
					throw new IllegalArgumentException("Mapped value [" + value + "] for scope key [" +
							scopeKey + "] is not an instance of required type [" + Scope.class.getName() +
							"] or a corresponding Class or String value indicating a Scope implementation");
				}
			});
		}
	}

}

View on GitHub (pinned to e8729d0438)

Solutions

1. Map each scope key to an actual Scope instance (or the Scope implementation Class / its fully-qualified class name String).
2. If using XML, ensure <entry key="..."><bean class="...MyScope"/></entry> refers to a Scope subtype.
3. Remove or correct the mis-typed entry.

Example fix

<!-- before -->
<bean class="o.s.b.f.config.CustomScopeConfigurer">
  <property name="scopes">
    <map><entry key="tenant" value="com.acme.TenantManager"/></map>
  </property>
</bean>
<!-- after -->
<bean class="o.s.b.f.config.CustomScopeConfigurer">
  <property name="scopes">
    <map><entry key="tenant"><bean class="com.acme.TenantScope"/></entry></map>
  </property>
</bean>

for (Map.Entry<String,Object> e : scopes.entrySet()) {
  Object v = e.getValue();
  boolean ok = v instanceof Scope || v instanceof Class || v instanceof String;
  if (!ok) throw new IllegalArgumentException(e.getKey() + " -> invalid scope value type " + v.getClass());
}

boolean validScopeValue(Object v) {
  return v instanceof Scope || v instanceof Class || v instanceof String;
}

When it happens

Trigger: Registering a custom scope via CustomScopeConfigurer.setScopes with a map value that is neither a Scope, a Class, nor a String - e.g. accidentally putting a bean instance, a Map, or an arbitrary object.

Common situations: XML <bean class="...CustomScopeConfigurer"> with a <map> entry whose value ref points at a non-Scope bean; programmatic configurer.getScopes().put(name, wrongObject); copy-paste wiring mistake using a factory or DTO instead of a Scope.

Related errors

• Not running in a ConfigurableBeanFactory: {beanFactory}
• Lifecycle annotation requires a no-arg method: {}
• Specified field type [{}] is incompatible with resource type
• Specified parameter type [{}] is incompatible with resource
• Value annotation must have a value attribute

AI-assisted analysis of spring-projects/spring-framework@e8729d0438 (2026-08-04). Data as JSON: /data/errors/3c76fe88532d41fa.json. Report an issue: GitHub.