IllegalArgumentException: Class must not be null after upgrading to Spring AI MCP Client 1.1.0

[think-gem]

IllegalArgumentException: Class must not be null after upgrading to Spring AI MCP Client 1.1.0

Description:

After upgrading from Spring AI version 1.0.3 to 1.1.0, my application fails to start with the following error:

java.lang.IllegalArgumentException: Class must not be null
	at org.springframework.util.Assert.notNull(Assert.java:181)
	at org.springframework.util.ReflectionUtils.getDeclaredMethods(ReflectionUtils.java:461)
	at org.springframework.util.ReflectionUtils.doWithMethods(ReflectionUtils.java:360)
	at org.springframework.util.ReflectionUtils.doWithMethods(ReflectionUtils.java:342)
	at org.springframework.ai.mcp.annotation.spring.AbstractClientMcpHandlerRegistry.scan(AbstractClientMcpHandlerRegistry.java:128)
	at org.springframework.ai.mcp.annotation.spring.AbstractClientMcpHandlerRegistry.postProcessBeanFactory(AbstractClientMcpHandlerRegistry.java:77)
	at org.springframework.ai.mcp.annotation.spring.ClientMcpSyncHandlersRegistry.postProcessBeanFactory(ClientMcpSyncHandlersRegistry.java:65)
	at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors(PostProcessorRegistrationDelegate.java:363)
	at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors(PostProcessorRegistrationDelegate.java:204)
	at org.springframework.context.support.AbstractApplicationContext.invokeBeanFactoryPostProcessors(AbstractApplicationContext.java:791)
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:609)
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:146)
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:752)
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:439)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:318)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1361)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1350)

Dependencies used:

<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

Root Cause Analysis:

The error originates from this line in AbstractClientMcpHandlerRegistry.java#L77:

Class<?> targetClass = AutoProxyUtils.determineTargetClass(beanFactory, beanName);

For the bean named shiroFilter, AutoProxyUtils.determineTargetClass(...) returns null. Although the bean definition exists in the beanFactory and can be retrieved normally, the internal call bd.getAttribute(ORIGINAL_TARGET_CLASS_ATTRIBUTE) returns null.

The shiroFilter bean is defined in ShiroAutoConfiguration.java

This worked perfectly in Spring AI 1.0.3, but breaks in 1.1.0.

Expected Behavior:
The application should start without throwing an IllegalArgumentException when scanning MCP handler beans, even if some beans (like shiroFilter) do not have a resolvable target class via AutoProxyUtils.determineTargetClass.

Suggested Fix:
Add a null check before calling ReflectionUtils.doWithMethods(targetClass, ...) to skip beans where targetClass is null. But I don't know if it's right.

[Kehrlann]

Your analysis is correct. I submitted a fix.

In the meantime, you can disable annotation scanning with:

spring.ai.mcp.client.annotation-scanner.enabled=false

[think-gem]

Thank you very much. I noticed that when the parameter spring.ai.mcp.client.annotation-scanner.enabled is set false, the auto-configuration class McpClientAnnotationScannerAutoConfiguration will be skipped, which leads to the following new issue: Description: Parameter 3 of method mcpSyncClients in org.springframework.ai.mcp.client.common.autoconfigure.McpClientAutoConfiguration required a bean of type 'org.springframework.ai.mcp.annotation.spring.ClientMcpSyncHandlersRegistry' that could not be found. Action: Consider defining a bean of type 'org.springframework.ai.mcp.annotation.spring.ClientMcpSyncHandlersRegistry' in your configuration.

…

---- Replied Message ---- | From | Daniel ***@***.***> | | Date | 11/19/2025 23:05 | | To | ***@***.***> | | Cc | ***@***.***> , ***@***.***> | | Subject | Re: [spring-projects/spring-ai] IllegalArgumentException: Class must not be null after upgrading to Spring AI MCP Client 1.1.0 (Issue #4917) | Kehrlann left a comment (spring-projects/spring-ai#4917) Your analysis is correct. I submitted a fix. In the meantime, you can disable annotation scanning with: spring.ai.mcp.client.annotation-scanner.enabled=false — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: ***@***.***>

[Kehrlann]

Ah, thank you! Will fix as well.

[think-gem]

https://github.com/spring-projects/spring-ai/pull/4918/files This commit is extremely useful to me.

I adopted a temporary solution. Thank you again.

/**
 * ClientMcp*HandlersRegistry: support beans with unresolvable types #4918
 * (To fix the issues in Spring AI 1.1.0, they need to be removed in 1.1.1.)
 * @author ThinkGem
 */
@Configuration
@ConditionalOnClass(McpLogging.class)
@ConditionalOnProperty(prefix = McpClientAnnotationScannerProperties.CONFIG_PREFIX, name = "enabled",
		havingValue = "true", matchIfMissing = true)
public class AiMcpClientFixConfig {

	@Bean
	@ConditionalOnMissingBean
	@ConditionalOnProperty(prefix = McpClientCommonProperties.CONFIG_PREFIX, name = "type", havingValue = "SYNC",
			matchIfMissing = true)
	public ClientMcpSyncHandlersRegistry clientMcpSyncHandlersRegistry() {
		return new ClientMcpSyncHandlersRegistry() {
			@Override
			public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
				this.beanFactory = beanFactory;
				Map<String, List<String>> elicitationClientToAnnotatedBeans = new HashMap<>();
				Map<String, List<String>> samplingClientToAnnotatedBeans = new HashMap<>();
				for (var beanName : beanFactory.getBeanDefinitionNames()) {
					if (!beanFactory.getBeanDefinition(beanName).isSingleton()) {
						// Only process singleton beans, not scoped beans
						continue;
					}

					// ClientMcp*HandlersRegistry: support beans with unresolvable types #4918
					Class<?> beanClass = AutoProxyUtils.determineTargetClass(beanFactory, beanName);
					if (beanClass == null) {
						// If we cannot determine the bean class, we cannot scan it before
						// it is really resolved. This is very likely an infrastructure-level
						// bean, not a "service" type, skip it entirely.
						continue;
					}
					var foundAnnotations = this.scan(beanClass);
					// #4918 end

					if (!foundAnnotations.isEmpty()) {
						this.allAnnotatedBeans.add(beanName);
					}
					for (var foundAnnotation : foundAnnotations) {
						if (foundAnnotation instanceof McpSampling sampling) {
							for (var client : sampling.clients()) {
								samplingClientToAnnotatedBeans.computeIfAbsent(client, c -> new ArrayList<>()).add(beanName);
							}
						}
						else if (foundAnnotation instanceof McpElicitation elicitation) {
							for (var client : elicitation.clients()) {
								elicitationClientToAnnotatedBeans.computeIfAbsent(client, c -> new ArrayList<>()).add(beanName);
							}
						}
					}
				}

				for (var elicitationEntry : elicitationClientToAnnotatedBeans.entrySet()) {
					if (elicitationEntry.getValue().size() > 1) {
						throw new IllegalArgumentException(
								"Found 2 elicitation handlers for client [%s], found in bean with names %s. Only one @McpElicitation handler is allowed per client"
									.formatted(elicitationEntry.getKey(), new LinkedHashSet<>(elicitationEntry.getValue())));
					}
				}
				for (var samplingEntry : samplingClientToAnnotatedBeans.entrySet()) {
					if (samplingEntry.getValue().size() > 1) {
						throw new IllegalArgumentException(
								"Found 2 sampling handlers for client [%s], found in bean with names %s. Only one @McpSampling handler is allowed per client"
									.formatted(samplingEntry.getKey(), new LinkedHashSet<>(samplingEntry.getValue())));
					}
				}

				Map<String, McpSchema.ClientCapabilities.Builder> capsPerClient = new HashMap<>();
				for (var samplingClient : samplingClientToAnnotatedBeans.keySet()) {
					capsPerClient.computeIfAbsent(samplingClient, ignored -> McpSchema.ClientCapabilities.builder()).sampling();
				}
				for (var elicitationClient : elicitationClientToAnnotatedBeans.keySet()) {
					capsPerClient.computeIfAbsent(elicitationClient, ignored -> McpSchema.ClientCapabilities.builder())
						.elicitation();
				}

				this.capabilitiesPerClient = capsPerClient.entrySet()
					.stream()
					.collect(Collectors.toMap(Map.Entry::getKey, entry -> entry.getValue().build()));
			}
		};
	}

}