Guidance for when to use class names and when to use class references is inaccurate

[Chr3is]

I have an AutoConfiguration, which uses @AutoConfigureBefore. The documentation states, that it's safe to specify classes that may not be on the classpath. However, a ClassNotFoundException is thrown if the auto configuration is included in a module, which does not have the class in the classpath:

@AutoConfiguration
@AutoConfigureBefore(LiquibaseAutoConfiguration.class)
public class AutoConfig {

}

Caused by: java.lang.IllegalStateException: Failed to generate bean name for imported class 'com.example.AutoConfig'
	at org.springframework.context.annotation.ConfigurationClassBeanDefinitionReader.registerBeanDefinitionForImportedConfigurationClass(ConfigurationClassBeanDefinitionReader.java:172)
	at org.springframework.context.annotation.ConfigurationClassBeanDefinitionReader.loadBeanDefinitionsForConfigurationClass(ConfigurationClassBeanDefinitionReader.java:145)
	at org.springframework.context.annotation.ConfigurationClassBeanDefinitionReader.loadBeanDefinitions(ConfigurationClassBeanDefinitionReader.java:124)
	at org.springframework.context.annotation.ConfigurationClassPostProcessor.processConfigBeanDefinitions(ConfigurationClassPostProcessor.java:464)
	at org.springframework.context.annotation.ConfigurationClassPostProcessor.postProcessBeanDefinitionRegistry(ConfigurationClassPostProcessor.java:316)
	at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanDefinitionRegistryPostProcessors(PostProcessorRegistrationDelegate.java:349)
	at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors(PostProcessorRegistrationDelegate.java:118)
	at org.springframework.context.support.AbstractApplicationContext.invokeBeanFactoryPostProcessors(AbstractApplicationContext.java:795)
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:603)
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:756)
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:445)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:321)
	at org.springframework.boot.test.context.SpringBootContextLoader.lambda$loadContext$2(SpringBootContextLoader.java:155)
	at org.springframework.util.function.ThrowingSupplier.get(ThrowingSupplier.java:58)
	at org.springframework.util.function.ThrowingSupplier.get(ThrowingSupplier.java:46)
	at org.springframework.boot.SpringApplication.withHook(SpringApplication.java:1465)
	at org.springframework.boot.test.context.SpringBootContextLoader$ContextLoaderHook.run(SpringBootContextLoader.java:600)
	at org.springframework.boot.test.context.SpringBootContextLoader.loadContext(SpringBootContextLoader.java:155)
	at org.springframework.boot.test.context.SpringBootContextLoader.loadContext(SpringBootContextLoader.java:114)
	at org.springframework.test.context.cache.DefaultCacheAwareContextLoaderDelegate.loadContextInternal(DefaultCacheAwareContextLoaderDelegate.java:247)
	at org.springframework.test.context.cache.DefaultCacheAwareContextLoaderDelegate.lambda$loadContext$0(DefaultCacheAwareContextLoaderDelegate.java:167)
	... 21 more
Caused by: java.lang.IllegalArgumentException: Could not find class [org.springframework.boot.liquibase.autoconfigure.LiquibaseAutoConfiguration]
	at org.springframework.util.ClassUtils.resolveClassName(ClassUtils.java:353)
	at org.springframework.core.annotation.TypeMappedAnnotation.adapt(TypeMappedAnnotation.java:451)
	at org.springframework.core.annotation.TypeMappedAnnotation.getValue(TypeMappedAnnotation.java:384)
	at org.springframework.core.annotation.TypeMappedAnnotation.asMap(TypeMappedAnnotation.java:273)
	at org.springframework.core.annotation.AbstractMergedAnnotation.asAnnotationAttributes(AbstractMergedAnnotation.java:191)
	at org.springframework.context.annotation.AnnotationBeanNameGenerator.determineBeanNameFromAnnotation(AnnotationBeanNameGenerator.java:143)
	at org.springframework.context.annotation.AnnotationBeanNameGenerator.generateBeanName(AnnotationBeanNameGenerator.java:110)
	at org.springframework.context.annotation.ConfigurationClassBeanDefinitionReader.registerBeanDefinitionForImportedConfigurationClass(ConfigurationClassBeanDefinitionReader.java:168)

This issue appeared during the spring boot 3.5 -> 4.0.x migration.

I provided a simple example to demonstrate this issue.

demo 9.zip

Maybe related: spring-projects/spring-framework#35631

[wilkinsona]

Thanks for the report.

I think the javadoc's inaccurate, although I believe that's the case in Spring Boot 3.5.x as well as 4.0.x. Your report suggests that you've seen a change in behavior when upgrading from 3.5 to 4.0 so we don't seem to have the complete picture here.

Please provide a minimal sample that uses Spring Boot 3.5 and does not fail when @AutoConfigureBefore or @AutoConfigureAfter references a class that is not on the classpath.

[Chr3is]

@wilkinsona I have to check this. The issue might not happen in this case with spring boot 3.5 because the used auto config classes e.g. LiquibaseAutoConfiguration in the annotations were always present in the classpath due to spring-boot-autoconfigure, which was modularized with spring boot 4.

[wilkinsona]

I think that's more than likely to be the case. It certainly is in my local experimentation. We can update the javadoc in 3.5.x and later.

As part of those updates, we should review all of the changes made for #48395. I think the new guidance only holds true for conditions and only for conditions that only match when all the referenced classes are present. If an annotated class can remain in use when a referenced class is absent, it needs to use a class name in the annotation to reference the class otherwise something introspecting the class's annotations will fail.

/cc @sbrannen

[Chr3is]

Using

@AutoConfiguration("MyAutoConfig") // <-- set bean name explicitly
@AutoConfigureBefore(LiquibaseAutoConfiguration.class)
public class AutoConfig {

}

would work as well.
It would be nice if spring would not fail due to a bean name generation rather falling back to a random unique name. However, I don't know the cases, where spring tries to load the class for which purpose.

[wilkinsona]

That wouldn't help as the problem's broader than just bean name generation. The @AutoConfigureBefore that references a non-existent class will hinder introspection of any of the class's annotations using any of Java's standard mechanisms.