skip to content

What are the ways to exclude a specific auto-configuration, and how do they differ?

level: middleimportance: should knowfreq 55%

answer

  1. exclude = Class[]
  2. excludeName = String[]
  3. spring.autoconfigure.exclude = CSV of FQNs
  4. removed before conditions run
  5. fail-fast on unknown excluded class

basics

~10 s

Use exclude (by class) or excludeName (by string) on @SpringBootApplication/@EnableAutoConfiguration, or set the property spring.autoconfigure.exclude. All prevent a named auto-configuration class from being applied.

solid answer

~40 s

There are two equivalent routes. Annotation-based: @SpringBootApplication(exclude = DataSourceAutoConfiguration.class) when the class is on the classpath, or excludeName = "..." with a fully-qualified string when it isn't compile-visible. Property-based: spring.autoconfigure.exclude in application.properties/yml, taking a comma-separated list of FQNs. Both remove the class from the candidate list before its conditions are even evaluated, so it never contributes beans. The property form is handy for environment-specific exclusions and doesn't require touching code. A subtle rule: Boot fails fast if you exclude a class that isn't actually on the classpath (to catch typos), though this strict check can be relaxed. Excluding is the right tool when an auto-config's conditions match but you specifically don't want its defaults — for example excluding DataSourceAutoConfiguration in a test that has a JDBC driver but no real DB.

code

java · 12 lines
java
// Form 1 & 2: annotation attributes
@SpringBootApplication(
    exclude = { DataSourceAutoConfiguration.class },
    excludeName = { "org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration" }
)
public class MyApp { }

// Form 3: property (application.yml)
// spring:
//   autoconfigure:
//     exclude:
//       - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

go deeper

for a junior

Know exclude= exists to turn off a specific auto-config, e.g. DataSourceAutoConfiguration.

for a middle

Distinguish exclude / excludeName / spring.autoconfigure.exclude and when to use each.

for a senior

Explain it removes candidates before conditions and the fail-fast typo check; contrast with back-off.

for a principal

Reason about cascading bean failures and choosing exclusion vs. targeted replacement in large multi-module apps.

## Why exclude at all Sometimes an auto-configuration's `@Conditional` guards match (its trigger class is on the classpath) but you still don't want its beans — a JDBC driver is present but you have no database, or you want to hand-roll security instead of Boot's defaults. Excluding removes that specific auto-configuration from the candidate set. ## The three forms 1. **`exclude` (Class array)** on `@EnableAutoConfiguration` or `@SpringBootApplication`: ```java @SpringBootApplication(exclude = { DataSourceAutoConfiguration.class }) ``` Use when the class is compile-time visible (you can reference `.class`). 2. **`excludeName` (String array)** — same effect but by fully-qualified name string, for classes not on your compile classpath: ```java @SpringBootApplication(excludeName = { "org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration" }) ``` 3. **`spring.autoconfigure.exclude` property** in `application.properties`/`application.yml`: ```properties spring.autoconfigure.exclude=\ org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\ org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration ``` Comma-separated FQNs. This is profile/environment-friendly — you can exclude only under a certain profile via `application-<profile>.properties`. All three are additive and combine; the effective exclusion set is the union. ## When exclusion happens in the pipeline `AutoConfigurationImportSelector` collects candidates from the imports file, then **removes excluded classes** (from both annotation attributes and the property) **before** running conditions. So an excluded class is dropped early and never evaluated. ## The typo/fail-fast rule Boot validates that every excluded name **is actually a known auto-configuration on the classpath**. If you exclude a class that isn't present, startup fails with a clear message — this catches misspelled FQNs. If you legitimately need to exclude something that may be absent, the strict check can be disabled via `spring.autoconfigure.exclude` semantics/`SpringApplication` settings, but the default is fail-fast, which is usually what you want. ## exclude vs. back-off — don't confuse them - **Back-off** (`@ConditionalOnMissingBean`) is automatic: define your own bean and the auto-config yields. No exclusion needed. - **exclude** is a blunt instrument: it removes the whole auto-configuration class regardless of conditions. Reach for it only when back-off isn't enough — e.g., you don't want *any* of the class's beans and can't simply provide a replacement. ## Common real uses - `DataSourceAutoConfiguration` / `HibernateJpaAutoConfiguration` in tests or apps that talk to a remote service instead of a DB but still transitively pull a JDBC driver. - `SecurityAutoConfiguration` when integrating a fully custom security stack. - `ManagementWebSecurityAutoConfiguration` to customize actuator security. ## Gotchas - Excluding by property vs annotation is a **union**, not an override — you can't 'un-exclude' via property. - Excluding an auto-config also disables everything that depended on its beans; expect cascading `NoSuchBeanDefinitionException` if something still needs them. - Test slices (`@DataJpaTest`, `@WebMvcTest`) already limit auto-config; exclude is rarely needed there.

  • What happens if you exclude a class that isn't on the classpath?
    By default Boot fails fast at startup with an error, treating it as a likely typo. It validates excluded names against known auto-configurations.
  • When would you prefer defining your own bean over excluding an auto-configuration?
    Almost always — back-off via @ConditionalOnMissingBean lets you replace one bean without disabling the whole auto-config. Exclude only when you want none of that class's beans.

saying these in an interview costs you the question

  • Believing exclude only works if the auto-config's conditions failed anyway (it removes it regardless).
  • Thinking the property form overrides/cancels the annotation form (they union).
  • Claiming excluding a class silently no-ops when the class is absent (it fails fast by default).

context

resolving links…