Spring Boot Auto-Configuration: How Beans Are Chosen
Spring Boot auto-configuration examines the application’s classpath, existing beans, configuration properties, and other conditions to decide which configuration classes and beans are appropriate. It creates eligible beans through Spring’s application context; it generally backs off when you provide a bean of your own for the same purpose.
What auto-configuration does
In a Spring application, a bean is an object managed by the Spring IoC container. Instead of constructing and connecting every infrastructure object yourself, you can let Boot configure common components such as a data source, JSON mapper, or web server. Auto-configuration is a set of ordinary Spring configuration classes that supplies those defaults when their prerequisites are met.
The usual starting point is @SpringBootApplication. It combines configuration, component scanning, and auto-configuration enablement. Component scanning discovers application classes you annotate, such as @Component, @Service, and @Controller. Auto-configuration is a separate mechanism: it imports candidate configuration classes supplied by Boot and other libraries, then evaluates whether each candidate should apply.
These are defaults, not a fixed list of objects that Boot always creates. A web application and a command-line application may receive different configurations, and adding or removing a dependency can change which candidates are available.
How Boot finds configuration candidates
In modern Spring Boot, auto-configuration classes are registered by libraries using the META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports resource. Boot uses the import mechanism to gather candidates when auto-configuration is enabled. Older Boot releases used META-INF/spring.factories for this purpose, so examples found online may reflect a different generation of Boot.
Candidate registration does not mean that every listed configuration runs. Boot filters and evaluates candidates using conditions. A configuration may require a particular class to be present, a web application to be active, a property to have a certain value, or a bean of a specified type to be missing. A library can therefore offer optional integration without forcing it on every application that includes the library.
How Boot decides which beans to create
Conditions determine whether a configuration class or an individual bean definition is eligible. Common condition types include:
@ConditionalOnClassand@ConditionalOnMissingClasscheck whether named classes can be found.@ConditionalOnBeanand@ConditionalOnMissingBeancheck the application context for matching beans.@ConditionalOnPropertychecks an environment property and, optionally, its value.@ConditionalOnWebApplicationand@ConditionalOnNotWebApplicationdistinguish web from non-web contexts.
For example, a data-source auto-configuration needs relevant JDBC classes on the classpath and normally needs database connection settings. Its bean definitions are subject to further conditions, including whether an appropriate data-source bean already exists. If you define your own matching bean, Boot’s conditional default can back off. This lets an application replace a default without disabling every unrelated auto-configuration.
Conditions are evaluated as the context is assembled, in an order that matters when one configuration depends on bean definitions from another. Boot’s configurations declare ordering where needed, but a condition should not be treated as an unrestricted query over every bean that might eventually exist. In particular, conditions are designed to inspect definitions and environment information at configuration time, not to invoke arbitrary application logic to discover future runtime state.
How eligible beans are created
Once a configuration is accepted, its bean definitions join those discovered through component scanning and other imports. A definition commonly comes from a method annotated @Bean; the method’s return type describes the bean, and its parameters can be resolved from other beans in the context. Boot may also use factory or registrar mechanisms where appropriate.
Spring then manages the bean lifecycle. It resolves dependencies, applies relevant bean post-processors, and creates instances when needed. Many beans are singletons by default, meaning one shared instance per application context, though scope and lazy initialization can change when and how an instance is created. Configuration is not necessarily the same as immediate object construction: definitions may be registered first and instantiated later.
Boot’s starter dependencies are useful because they bring compatible libraries together, but a starter does not itself guarantee a particular bean. The auto-configuration still checks classes, properties, application type, and existing definitions. A missing database URL, for instance, can prevent a usable data source even when JDBC support is present.
How to customize or replace defaults
The least disruptive customization is usually to supply the property intended for the setting. Many auto-configurations bind external configuration into a properties class, allowing values in application.properties or application.yaml to adjust behavior. Consult the documentation for the Boot version and library you use: property names and defaults are part of that version’s configuration API.
If a setting is not enough, define a bean of the relevant type. When the auto-configuration uses @ConditionalOnMissingBean, your bean typically takes the place of its default. Check the condition report if that does not happen; there may be another bean of the same type, a qualifier or name requirement, or a condition that is not satisfied.
You can exclude an auto-configuration when it is inappropriate, using the supported exclusion options on @SpringBootApplication or @EnableAutoConfiguration, or the relevant configuration property. Prefer a targeted exclusion over removing a broad dependency: the latter can also remove classes that other parts of the application need.
Diagnosing unexpected configuration
If a bean is missing or a default appears unexpectedly, first identify the exact Boot and library versions, then inspect the conditions rather than guessing. The condition evaluation report explains which auto-configurations matched and which did not, often including a reason such as a missing class, property, or bean.
- Run the application with the
--debugoption to request the auto-configuration condition report. - Check that the expected dependency is present at runtime, not merely in a build configuration that does not reach the application.
- Verify active profiles and effective property values, including environment variables and command-line overrides.
- Look for duplicate or competing bean definitions and confirm the expected type and qualifiers.
- Use the report to identify the specific condition that failed before adding exclusions or changing scan boundaries.
A frequent misconception is that Boot scans the entire classpath and automatically turns every class into a bean. Classpath presence only makes certain integrations possible; a candidate must be registered and its conditions must match. Likewise, component scanning and auto-configuration are related parts of startup, but they discover beans in different ways.
Frequently Asked Questions
Does Spring Boot create every bean listed in an auto-configuration class?
No. The class or individual bean methods may have conditions. Only definitions whose requirements match are registered, and some beans may be instantiated later than context startup.
Will my own bean override an auto-configured bean?
Often, if the auto-configuration is conditional on a matching bean being absent. This depends on the condition and matching rules, so check the report and the bean’s type, name, and qualifiers rather than assuming every custom bean replaces a default.
What is the difference between a starter and auto-configuration?
A starter is a dependency bundle that simplifies adding related libraries. Auto-configuration is the conditional configuration logic that can use those libraries to register beans. A starter can enable a possibility without guaranteeing that its beans are created.
How do I find out why an auto-configuration did not apply?
Start the application with --debug and read the condition evaluation report. It shows positive and negative matches, helping you identify missing classes, properties, or existing beans.
Can I disable one auto-configuration?
Yes. Use the supported exclusion mechanism for that specific configuration, or its documented property if one exists. Confirm the exact configuration class for your Boot version, since class names and registration details can differ across releases.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.