How to Exclude Auto Configuration in Spring Boot Apps
Exclude a Spring Boot auto configuration class with an annotation or property, and learn when a custom bean or a profile is the better tool.

Boot applies what it finds, and sometimes it finds too much: a JDBC driver for tests only, a library that triggers Security, a datasource you do not want. You can remove a configuration entirely.
With the annotation
@SpringBootApplication(exclude = {
DataSourceAutoConfiguration.class,
HibernateJpaAutoConfiguration.class
})
public class ReportingApplication { }The Java compiler checks the class names, so a rename is caught. In Spring Boot 4 the auto-configurations are split across modules, so the package may differ from what older guides show. Let the IDE import the class rather than typing a package from memory.
With a property
spring.autoconfigure.exclude=org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfigurationThe property takes a comma-separated list, and it lets a profile decide:
spring.autoconfigure.exclude=com.example.audit.AuditAutoConfigurationThe same exclusion can come from an environment variable, SPRING_AUTOCONFIGURE_EXCLUDE, which suits a container where the image is fixed but behaviour differs.
When the class may be absent
@SpringBootApplication(excludeName = "org.springframework.boot.security.autoconfigure.SecurityAutoConfiguration")excludeName accepts a string, so the code compiles when the dependency is optional.
Check that it took effect
Start with --debug and look in the Exclusions section of the conditions report:
Exclusions:
-----------
org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfigurationIf you name a class that is not an auto-configuration, Boot stops with The following classes could not be excluded because they are not auto-configuration classes. Move the exclusion to a real configuration class, or remove it.
Alternatives that are often better
| You want | Do this instead |
|---|---|
A different DataSource | Define your own bean, and the default backs off |
| No web server | spring.main.web-application-type=none |
| Security off in a test | Test slices or a test configuration, not production exclusion |
| One feature off | Its property, such as management.endpoint.x.enabled=false |
An exclusion that removes the data source also disables everything built on it. Excluding DataSourceAutoConfiguration while JPA is on the classpath produces the failed to configure a DataSource style of error, only later in startup. Remove or exclude the whole family together.
The two forms are merged, not ranked
When you use both the annotation and the property, Boot combines the lists, so an exclusion in application.properties and another in @SpringBootApplication are both applied. That is convenient and it hides the source of a surprise: a teammate adds a property in a profile file, and the data source disappears in one environment only. When something is missing and the code looks right, search for spring.autoconfigure.exclude in every config file, in environment variables and in the arguments the container passes, before reading any more code.
Exclusions we actually use
Three come up repeatedly. The first is the default user service that Spring Security creates when it finds no UserDetailsService: it prints a generated password at startup, and a service that authenticates through a JWT or an external provider does not want that. Exclude UserDetailsServiceAutoConfiguration, or better define a bean that makes the default back off. The second is the data source in a command-line tool that happens to share a dependency set with a database application. The third is a feature module that a shared starter turns on for every service, such as a metrics exporter you do not run in tests.
Excluding in tests
A test slice already loads a narrow set of configurations, so exclusion is rarely needed there. For a full @SpringBootTest that must run without a database, use the property on the annotation: @SpringBootTest(properties = "spring.autoconfigure.exclude=..."). That keeps the exclusion scoped to the test class and out of production configuration. Remember that excluding an auto-configuration does not remove beans defined by your own @Configuration classes, so a repository interface that still needs a data source fails with the very error you were trying to avoid.
Writing your own and making it easy to exclude
If you publish a library with its own auto-configuration, register it in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports and annotate it with @AutoConfiguration. Guard it with @ConditionalOnMissingBean and @ConditionalOnProperty so users can turn it off with a property, which is kinder than asking them to exclude a class from your internals. Document the property in the library's reference. A class name is an implementation detail that you may rename, and a property is a contract.
Lazy initialization is a different tool
spring.main.lazy-initialization=true delays bean creation until first use. It speeds up startup and moves a missing-dependency error from boot to the first request, which is the opposite of what an exclusion does. Use it to cut startup time in development, and avoid it in production unless you have tested every code path for a first-request failure.
Reviewing exclusions over time
An exclusion is a decision with a reason, and the reason goes stale. Leave a one-line comment beside every exclusion that says why it is there and what would let you remove it. A year later, when the shared starter that forced the exclusion has been fixed, the comment lets a new person delete the line with confidence instead of leaving it because nobody remembers.
Check the conditions report after dependency upgrades too. A Boot upgrade can split or rename an auto-configuration class, and an excludeName string that no longer matches is skipped silently, so the feature you meant to disable comes back on without any error.
A short checklist before you exclude
Ask four questions in order. Does a property switch the behavior off? Does defining my own bean make the default back off? Is the problem only in tests, where a slice or a test property is the narrower tool? And what else depends on the class I am about to remove? Only when all four answers point to exclusion does the annotation earn its place, and then write the reason beside it for whoever reads it next.
Where this does not apply
An exclusion applies to the whole application context. For one test, use a test slice or @ImportAutoConfiguration. In a library, do not exclude on behalf of an application; document the property instead. How the list of candidates is built is in how auto-configuration works. The Actuator reference lists the endpoints. The reference is Disabling Specific Auto-configuration Classes, and the container explains why backing off by bean works.


