How Auto-configuration Works

Before Spring Boot, starting a web application required assembling infrastructure by hand. You had to declare a DispatcherServlet, configure content negotiation, register Jackson message converters, and set up an embedded server factory. This boilerplate was identical across projects, but hiding it inside a closed framework prevented teams from customizing the beans they actually needed.

Auto-configuration solves this by turning common infrastructure into conditional configuration. Boot provides the defaults, but evaluates conditions at startup to ensure it never overrides your explicit choices.

Auto-configuration is not scanning. When you use @SpringBootApplication, Boot scans your own packages for @Component and @Bean methods. Separately, @EnableAutoConfiguration tells Boot to read META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports from every jar on the classpath. These imports name candidate configuration classes.

1. 01Candidate discovery: Boot loads the list of candidate configuration classes from imported framework modules.
2. 02Condition evaluation: Boot evaluates @Conditional annotations on each candidate against the current classpath, properties, and existing beans.
3. 03Registration: Candidates whose conditions match are registered as BeanDefinitions.
4. 04Instantiation: The Spring container creates the actual bean instances from those definitions.

Consider JacksonAutoConfiguration in Spring Boot 3.5. It does not apply unconditionally to every application. Its declaration proves it only activates when Jackson is actually on the classpath.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

@AutoConfiguration
@ConditionalOnClass(ObjectMapper.class)
public class JacksonAutoConfiguration {

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(Jackson2ObjectMapperBuilder.class)
    static class JacksonObjectMapperConfiguration {

        @Bean
        @Primary
        @ConditionalOnMissingBean
        ObjectMapper jacksonObjectMapper(Jackson2ObjectMapperBuilder builder) {
            return builder.createXmlMapper(false).build();
        }
    }
}

The class-level @ConditionalOnClass ensures Boot ignores this configuration entirely if your build does not include Jackson. A positive outer match does not guarantee every nested configuration matches. The nested JacksonObjectMapperConfiguration evaluates its own @ConditionalOnClass(Jackson2ObjectMapperBuilder.class) before deciding to evaluate the @Bean method, which finally checks @ConditionalOnMissingBean to back off if you define your own ObjectMapper. This is the sanctioned override path.

We can prove this behavior programmatically using Boot's ApplicationContextRunner. This utility lets us run a focused context test with specific auto-configurations and our own beans.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
    .withConfiguration(AutoConfigurations.of(JacksonAutoConfiguration.class));

@Test
void autoConfigurationBacksOffWhenUserBeanIsPresent() {
    this.contextRunner.withUserConfiguration(UserConfiguration.class).run((context) -> {
        assertThat(context).hasSingleBean(ObjectMapper.class);
        assertThat(context).getBean("myCustomMapper").isSameAs(context.getBean(ObjectMapper.class));
    });
}

@Configuration(proxyBeanMethods = false)
static class UserConfiguration {
    @Bean
    ObjectMapper myCustomMapper() {
        return new ObjectMapper();
    }
}

When we supply UserConfiguration, Boot evaluates JacksonAutoConfiguration, sees our myCustomMapper bean, and skips its own default. The test proves that the container holds exactly one ObjectMapper, and it is the one we defined.

When a bean is missing or unexpected, do not guess. Run your application with the --debug flag to print the Condition Evaluation Report. This trace explains exactly why every candidate matched or failed.

Positive matches:
-----------------
   JacksonAutoConfiguration matched:
      - @ConditionalOnClass found required class 'com.fasterxml.jackson.databind.ObjectMapper' (OnClassCondition)

   JacksonAutoConfiguration.JacksonObjectMapperConfiguration matched:
      - @ConditionalOnClass found required class 'org.springframework.http.converter.json.Jackson2ObjectMapperBuilder' (OnClassCondition)

Negative matches:
-----------------
   JacksonAutoConfiguration.JacksonObjectMapperConfiguration#jacksonObjectMapper:
      - @ConditionalOnMissingBean (types: com.fasterxml.jackson.databind.ObjectMapper; SearchStrategy: all) found beans of type 'com.fasterxml.jackson.databind.ObjectMapper' myCustomMapper (OnBeanCondition)

This report confirms the outcome of our experiment: the outer configuration class and its nested configuration matched because Jackson was on the classpath, but the specific bean method backed off because it found myCustomMapper.

A common misconception is assuming that because Tomcat started on port 8080, MVC auto-configuration succeeded and any subsequent 404 must simply be an unmapped path. In reality, Tomcat starting does not even prove that ServletWebServerFactoryAutoConfiguration ran—if an engineer manually declared a custom @Bean public TomcatServletWebServerFactory servletWebServerFactory(), the default auto-configuration completely backed off due to @ConditionalOnMissingBean, yet Tomcat still started! Tomcat starting only proves that a web server factory bean was resolved and bound to a port. A subsequent 404 can stem from three distinct architectural failure modes: MVC auto-configuration did not match, the controller bean was never instantiated, or handler mappings did not register the expected URI.

Use a structured three-step diagnostic tree instead of guessing: (1) Run with --debug and inspect the Condition Evaluation Report to verify that DispatcherServletAutoConfiguration and WebMvcAutoConfiguration matched. (2) Query /actuator/beans to confirm whether your @RestController exists in the ApplicationContext. If absent, do not jump to package-scanning conclusions: an absent bean may be caused by package boundaries outside the @SpringBootApplication scan tree, but equally by @Profile mismatches (e.g. @Profile("dev") running under prod), conditional evaluations (@ConditionalOnProperty, @ConditionalOnClass, @ConditionalOnBean), or @ComponentScan.Filter exclusions. Inspect the Condition Evaluation Report under "Negative matches" to identify the exact condition that backed off. (3) Query /actuator/mappings to verify that DispatcherServlet mapped the exact HTTP verb and path—if the bean exists in the context but returns 404, inspect server.servlet.context-path, path variable regular expressions, trailing slash mismatches, or unmapped HTTP methods.