Spring Boot auto-configuration is often summed up as “it configures things automatically”, which is no help when a bean appears that you did not expect, or fails to appear when you did. The useful picture has three parts: how Boot decides which configuration to apply, when it backs off in favour of your own beans, and how to read the conditions report that records every one of those decisions. All you need beforehand is what @Configuration, @Bean and component scanning do; the examples use Spring Boot 3.x, where registration moved from spring.factories to a dedicated imports file.
@SpringBootApplication includes @EnableAutoConfiguration, which loads a list of auto-configuration classes from META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports in every jar on the classpath. Each class is guarded by conditions, mainly @ConditionalOnClass (is the library present?), @ConditionalOnProperty (is it switched on?) and @ConditionalOnMissingBean (has the user already defined one?). Auto-configuration runs after your own configuration is registered, so defining your own bean makes Boot’s default back off. You inspect the decisions with --debug or the conditions actuator endpoint.
Inside an auto-configuration class and its imports file
Here is a simplified version of what an auto-configuration class looks like. Real ones in spring-boot-autoconfigure follow the same pattern.
@AutoConfiguration
@ConditionalOnClass(ObjectMapper.class) // only if Jackson is on the classpath
@EnableConfigurationProperties(JacksonProperties.class)
public class SimpleJacksonAutoConfiguration {
@Bean
@ConditionalOnMissingBean // back off if the app defines its own
ObjectMapper objectMapper(JacksonProperties props) {
ObjectMapper mapper = new ObjectMapper();
// apply spring.jackson.* properties here
return mapper;
}
}And it is registered by a plain text file, one class name per line:
# src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.example.autoconfigure.SimpleJacksonAutoConfigurationThe ordering is the key. Spring first processes your @Configuration classes and scanned components. Only then does the AutoConfigurationImportSelector (a deferred import selector) process auto-configurations. By the time @ConditionalOnMissingBean is evaluated, your beans are already registered as definitions, so the condition can see them. This is also why @ConditionalOnMissingBean is documented as reliable only inside auto-configuration classes: in your own configuration the order is not guaranteed.
Auto-configurations can order themselves relative to each other with @AutoConfiguration(after = DataSourceAutoConfiguration.class), which is how JPA configuration waits for the DataSource.
From a property tweak to a full exclusion
Properties first: add a starter and keep the defaults
Add spring-boot-starter-web. Jackson arrives transitively, JacksonAutoConfiguration sees ObjectMapper on the classpath, finds no user-defined mapper, and creates one configured from spring.jackson.* properties. Your controllers serialize JSON without any code.
spring:
jackson:
default-property-inclusion: non_nullThe first lever is properties. Most customization should stop here because you keep all of Boot’s other defaults.
Customizers: adjust Boot’s bean without replacing it
Many auto-configurations expose customizer callbacks that adjust Boot’s bean rather than replacing it:
@Configuration
class JsonConfig {
@Bean
Jackson2ObjectMapperBuilderCustomizer strictPrimitives() {
return builder -> builder.featuresToEnable(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES);
}
}Customizers compose: several libraries can each contribute one, and Boot still owns the bean.
Replacing the bean entirely
If you define your own ObjectMapper, @ConditionalOnMissingBean sees it and Boot creates nothing.
@Configuration
class JsonConfig {
@Bean
ObjectMapper objectMapper() {
return JsonMapper.builder().findAndAddModules().build();
}
}This is powerful and dangerous. Your mapper does not receive spring.jackson.* properties or the customizers shown above, because those were wired into the bean you replaced.
Reading the conditions report
Start the app with --debug (or debug=true in properties). Boot prints a report grouped into positive matches, negative matches, exclusions and unconditional classes.
============================
CONDITIONS EVALUATION REPORT
============================
Positive matches:
-----------------
DataSourceAutoConfiguration matched:
- @ConditionalOnClass found required classes 'javax.sql.DataSource', ... (OnClassCondition)
Negative matches:
-----------------
JacksonAutoConfiguration.JacksonObjectMapperConfiguration#jacksonObjectMapper:
Did not match:
- @ConditionalOnMissingBean (types: com.fasterxml.jackson.databind.ObjectMapper; SearchStrategy: all)
found beans of type 'com.fasterxml.jackson.databind.ObjectMapper' objectMapper (OnBeanCondition)That negative match tells you exactly which of your beans caused the back-off. With Actuator, /actuator/conditions returns the same data as JSON.
Excluding an auto-configuration when you must
To turn off an entire auto-configuration, exclude it by class or property:
@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class App { }spring:
autoconfigure:
exclude: org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfigurationExclusion is a blunt tool. Prefer it for things you genuinely do not want, such as a library that drags in a DataSource dependency for a service with no database (see the failed to configure a DataSource guide).
A custom ObjectMapper that switched off spring.jackson.*
Picture a team that replaces Boot’s mapper with JsonMapper.builder().findAndAddModules().build() so it can register a money module. Within a day, API responses change: null fields reappear and java.time values come back as numeric timestamps or arrays instead of ISO-8601 strings. Nobody touched application.yml, which still says default-property-inclusion: non_null.
The conditions report shows jacksonObjectMapper in the negative matches because the custom mapper exists. Boot’s mapper, the one that applied spring.jackson.*, was never created. The property is now ignored, and so are Boot’s own Jackson defaults, such as turning off WRITE_DATES_AS_TIMESTAMPS.
The fix is to customize instead of replace:
@Configuration
class JsonConfig {
@Bean
Module moneyModule() {
return new MoneyModule(); // any com.fasterxml.jackson.databind.Module bean is registered by Boot
}
}Boot’s Jackson auto-configuration registers every Module bean it finds, so the custom module is added and all properties keep working. A wider lesson: before you define a bean of a type Boot configures, check whether a property, customizer or module bean already gives you the hook.
Testing back-off with ApplicationContextRunner
ApplicationContextRunner tests auto-configuration without starting a server. It is the same tool the Spring Boot team uses.
class SimpleJacksonAutoConfigurationTest {
private final ApplicationContextRunner runner = new ApplicationContextRunner()
.withConfiguration(AutoConfigurations.of(SimpleJacksonAutoConfiguration.class));
@Test
void createsMapperByDefault() {
runner.run(ctx -> assertThat(ctx).hasSingleBean(ObjectMapper.class));
}
@Test
void backsOffWhenUserDefinesOne() {
runner.withBean("custom", ObjectMapper.class, ObjectMapper::new)
.run(ctx -> assertThat(ctx).hasSingleBean(ObjectMapper.class)
.hasBean("custom"));
}
@Test
void skipsWhenJacksonMissing() {
runner.withClassLoader(new FilteredClassLoader(ObjectMapper.class))
.run(ctx -> assertThat(ctx).doesNotHaveBean(ObjectMapper.class));
}
}Where people go wrong with auto-configuration
- “Auto-configuration uses component scanning.” It does not. Auto-configuration classes live in libraries and are loaded from the imports file. Placing them under your scanned package actually breaks ordering.
- “Boot uses spring.factories.” That was Spring Boot 2. Boot 3 reads
AutoConfiguration.imports;spring.factoriesregistration for auto-configuration is no longer supported. - Using
@ConditionalOnMissingBeanin ordinary application configuration gives results that depend on the order bean definitions happen to be registered, which is only defined for auto-configuration. - Replacing a bean to change one setting throws away every
spring.*property and customizer that applied to Boot’s version, as theObjectMapperexample above shows. - Excluding auto-configuration to fix an error you have not read. The conditions report and the failure analyzer usually point to the real cause.
Follow-ups on starters, @ConditionalOnBean and proxies
How would you write your own starter? Put the @AutoConfiguration class and the imports file in an -autoconfigure module, guard every bean with conditions, bind settings through @ConfigurationProperties, and provide a -starter module that only pulls dependencies.
What is @ConditionalOnBean and why is it risky? It creates a bean only if another bean exists. It is order sensitive; use it in auto-configuration with after = ordering, not in user configuration.
What does proxyBeanMethods = false do on @AutoConfiguration? It is the default for @AutoConfiguration. Boot does not CGLIB-proxy the class, so calling one @Bean method from another creates a new instance; inject dependencies as method parameters instead.
How do you see which auto-configurations are active at runtime? Query /actuator/conditions on a running instance, or start the app with --debug and read the report it prints.
An interview question to try: two DataSources break JPA
Your service connects to two databases. You define two DataSource beans and suddenly Spring Data JPA fails to start, and so does Flyway. Explain what happened in terms of auto-configuration and how you would fix it.
How to answer it
DataSourceAutoConfiguration backed off because @ConditionalOnMissingBean(DataSource.class) found your beans, which is expected. Boot’s Hibernate JPA configuration, however, is guarded by @ConditionalOnSingleCandidate(DataSource.class): with two candidates and no @Primary, it backs off as well, no entityManagerFactory is created, and the repositories fail with “required a bean named ‘entityManagerFactory’ that could not be found” (see no qualifying bean). Flyway likewise expects one unambiguous DataSource. The conditions report lists the JPA configuration under negative matches with the two bean names it found. Mark one DataSource as @Primary so Boot’s JPA and Flyway configurations use it, and configure the second EntityManagerFactory and transaction manager explicitly for the other database. The reasoning to show: you know Boot backs off by type, you read the conditions report to confirm, and you resolve ambiguity deliberately rather than excluding auto-configuration.