How Spring Boot Auto Configuration Works Under the Hood
See how Spring Boot auto configuration is discovered, which conditions decide whether a configuration applies, and why your own beans always win.

Spring Boot's most useful trick is that a DataSource appears when you add a driver and a property, a DispatcherServlet appears when you add the web starter, and Jackson is configured without a line of code. None of it is magic, and understanding the mechanism turns a class of baffling startup behaviour into something you can read off a report. Auto-configuration is a list of ordinary @Configuration classes that Spring evaluates at startup, each guarded by conditions that ask what is on the classpath, what beans you have already defined and what properties are set. This post follows that process step by step in Spring Boot 4 on JDK 25, then shows how to see what happened in your own application.
Step 1: the entry point
@SpringBootApplication is three annotations in one: @SpringBootConfiguration, @ComponentScan and @EnableAutoConfiguration. The last is the one that matters here. It imports a selector that reads a file from every jar on the classpath:
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.importsEach line of the file is the name of an auto-configuration class. The Boot jar spring-boot-autoconfigure lists a few hundred of them. A starter, or a library that supports Boot, adds its own AutoConfiguration.imports file and its classes join the list. The older mechanism, spring.factories with an EnableAutoConfiguration key, was removed for this purpose in Boot 3; if you maintain a library from the older era, move the entries to the .imports file. The selector collects all names, removes those you excluded, and hands the list to the container as candidates, not as certainties. The candidates are evaluated after your own configuration is processed, which is what step 3 depends on. Excluding one on purpose is covered in excluding auto-configuration.
Step 2: each class is guarded
An auto-configuration class is annotated @AutoConfiguration and carries conditions. A simplified version of the one for Jackson shows the shape:
@AutoConfiguration
@ConditionalOnClass(ObjectMapper.class)
public class JacksonAutoConfiguration {
@Bean
@Primary
@ConditionalOnMissingBean
ObjectMapper jacksonObjectMapper(Jackson2ObjectMapperBuilder builder) {
return builder.createXmlMapper(false).build();
}
}@ConditionalOnClass(ObjectMapper.class) means: apply this class only if Jackson is on the classpath. The check uses the class name as a string, via ASM, so the class can be absent without a ClassNotFoundException while Boot reads the annotation. That is why you can add spring-boot-starter-web without Jackson and still start; the Jackson configuration is skipped. @ConditionalOnMissingBean on the method means: define this bean only if the context has no ObjectMapper already.
The common conditions are a short list. @ConditionalOnClass and @ConditionalOnMissingClass test the classpath. @ConditionalOnBean and @ConditionalOnMissingBean test the container. @ConditionalOnProperty tests configuration, with a name, an expected value and a default. @ConditionalOnWebApplication and its reactive and servlet variants test the kind of application. @ConditionalOnResource tests a file. @ConditionalOnExpression evaluates SpEL, and @ConditionalOnCloudPlatform the environment. You compose them freely, and the class applies only when every condition passes. The pattern is also available to you for your own configuration, see conditional beans for the profile-based variant.
Step 3: your beans are registered first
Order is the reason @ConditionalOnMissingBean works. The container processes your own @Configuration classes and component-scanned beans first, and auto-configuration classes afterwards. By the time the Jackson class asks "is there already an ObjectMapper?", your bean definitions exist, so if you declared one, Boot backs off:
@Configuration
class JsonConfig {
@Bean
ObjectMapper objectMapper() {
return new ObjectMapper().findAndRegisterModules().disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
}
}That single user-defined bean replaces the auto-configured one entirely, and every setting Boot would have applied, such as the spring.jackson.* properties, is lost with it. This is the rule behind "auto-configuration backs off when you define your own", and it is also the source of a classic surprise: you define a bean to change one detail and silently lose the other defaults. To customise instead of replace, use the hooks Boot provides, such as a Jackson2ObjectMapperBuilderCustomizer bean, or the properties. The conditions apply to bean types, not names, and the container's rules for resolving ambiguity are described in how the Spring container works.
Step 4: ordering
Some auto-configurations depend on others: the JPA configuration needs the DataSource to exist. Declare it with the annotation attributes @AutoConfiguration(after = DataSourceAutoConfiguration.class) or before = .... Boot sorts the candidates by these constraints, alphabetically within them, and applies them in that order. Without correct ordering, a @ConditionalOnBean test may run before the bean it looks for is registered, and the result is a configuration that is skipped in a way that depends on the order of jars on the classpath. The rule for authors: use @ConditionalOnBean only in auto-configuration, never in ordinary user configuration, because only auto-configuration has a defined ordering relative to the beans it tests. In your own @Configuration classes, conditions on beans are fragile for the same reason.
See what happened
Never guess which auto-configurations applied. Ask Boot. Start the application with --debug, or set debug=true:
java -jar app.jar --debugThe log then prints a conditions evaluation report in four groups:
Positive matches:
DataSourceAutoConfiguration matched:
- @ConditionalOnClass found required classes 'javax.sql.DataSource', 'org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType'
Negative matches:
MongoAutoConfiguration:
Did not match:
- @ConditionalOnClass did not find required class 'com.mongodb.client.MongoClient'
Exclusions:
None
Unconditional classes:
org.springframework.boot.autoconfigure.context.ConfigurationPropertiesAutoConfigurationPositive matches are the classes that applied, with the reasons. Negative matches are the ones that did not, each with the failing condition, which is the answer to "why did Boot not configure X?". The same report is available at run time from the conditions endpoint of the Actuator. Details and tricks are in the conditions report. For bean wiring failures that are not about conditions, debugging bean wiring problems covers the container-level tools.
Two practical uses. When an expected bean is missing, find its auto-configuration class in the negative matches and read the failing condition: a missing property, a class not on the classpath, a bean that is already defined. When an unexpected bean appears, such as a security filter chain you did not ask for, find its class in the positive matches and exclude it or satisfy it with your own definition.
Writing your own
A library that wants this behaviour packages an @AutoConfiguration class, lists it in META-INF/spring/...AutoConfiguration.imports, and guards every bean with @ConditionalOnMissingBean so users can override it. Properties go in a @ConfigurationProperties class so that the IDE gets metadata. Put the configuration and the starter dependency in separate modules, conventionally acme-spring-boot-autoconfigure and acme-spring-boot-starter. The complete recipe is in writing your own starter, and the project layout that makes component scanning find your code is in package layout.
Where this does not apply
Auto-configuration is a Spring Boot feature, not a Spring Framework one; a plain Spring application has none of it and configures everything explicitly. And the process runs at startup on the JVM: in a native image, the conditions are evaluated at build time, so a property that changes a condition cannot be changed at run time. The authoritative text is the auto-configuration chapter and the source in the Spring Boot repository, which is readable and worth opening for the class you are debugging.


