Spring Boot Internals: How Auto-Configuration Really Works

Short answer

DeferredImportSelector defers its import selection until after all regular @Configuration classes in the application have been parsed. Spring Boot relies on this timing to guarantee that user-defined beans always take priority over auto-configured ones.

The mechanism in detail

During ConfigurationClassParser.parse(), Spring walks the configuration graph in two passes:

1. Immediate imports from ImportSelector are processed inline as each @Configuration is visited.
2. Deferred imports from DeferredImportSelector are collected into a DeferredImportSelectorHandler and processed last, after the entire user configuration graph has been parsed and all user bean definitions registered.

Why this matters for @ConditionalOnMissingBean

Consider this scenario:

java// User code
@Configuration
public class MyAppConfig {
    @Bean public DataSource customDataSource() { ... }
}

// Spring Boot auto-config
@AutoConfiguration
public class DataSourceAutoConfiguration {
    @Bean @ConditionalOnMissingBean
    public DataSource dataSource() { ... }
}

Because AutoConfigurationImportSelector is deferred, by the time DataSourceAutoConfiguration's bean definitions are being evaluated, customDataSource is already in the BeanDefinitionRegistry. OnBeanCondition finds it and returns false, causing the auto-configured bean to back off.

Secondary benefit — grouping

DeferredImportSelector.Group lets related selectors share context. Spring Boot uses AutoConfigurationGroup to collect all auto-configuration imports together, then sort them via AutoConfigurationSorter (topological sort using @AutoConfigureBefore/@AutoConfigureAfter) before they're handed back to Spring.

What would break without deferred semantics?

If AutoConfigurationImportSelector was a plain ImportSelector, the order of @Configuration class processing would determine which bean wins — which is effectively undefined (depends on classpath order, component scan order). Every Spring Boot app would have flaky bean-override behaviour. Deferred selectors make Spring Boot's "user always wins" contract robust.

The two phases

Spring Boot evaluates conditions in two distinct phases driven by the ConfigurationPhase enum:

1. PARSE_CONFIGURATION — runs when the @Configuration class metadata is being parsed. No class loading, no bean factory access — just annotation metadata and classpath presence checks.
2. REGISTER_BEAN — runs after all configuration parsing is complete, when bean definitions are being finalized. Has access to the full BeanFactory and can inspect existing bean definitions.

Why @ConditionalOnClass runs in PARSE_CONFIGURATION

OnClassCondition uses ASM bytecode scanning of the classpath index (spring.components) — it never triggers class loading. This is deliberate: loading com.mongodb.MongoClient just to check if MongoDB is present would pull in the entire Mongo driver's static initializers (thread pools, logging frameworks, etc.), which is catastrophic for startup time.

The check is essentially:

java — simplifiedprivate boolean isPresent(String className, ClassLoader cl) {
    try {
        ClassUtils.forName(className, cl);   // fails fast without init
        return true;
    } catch (Throwable ex) {
        return false;
    }
}

Further, OnClassCondition implements AutoConfigurationImportFilter, so this check happens in bulk during Step 4 of AutoConfigurationImportSelector — before the auto-config classes are even passed to Spring for processing. Hundreds of candidates are filtered in milliseconds.

Why @ConditionalOnMissingBean must run in REGISTER_BEAN

To answer "does a bean of type DataSource exist?", Spring needs to consult the BeanFactory — which doesn't exist during parse time. It needs:

• The full set of bean definitions (including user configs that haven't been parsed yet at class-declaration time).
• Knowledge of factory method return types — which requires resolving @Bean method signatures.
• Generic type resolution for parameterized beans (e.g. Repository<User>).

The performance contract

This two-phase split is what makes Spring Boot's startup viable. If every condition had to run in REGISTER_BEAN (requiring a fully-populated BeanFactory), you'd have to parse and register every candidate auto-config's bean definitions just to decide whether to skip it. Instead, classpath-based conditions filter 80% of candidates before they ever enter the parsing phase.

Pitfall — conditions that read from BeanFactory at parse time

You can override getConfigurationPhase() in a custom Condition. If you return REGISTER_BEAN and the condition depends on bean existence, it works. If you try to query the BeanFactory from a PARSE_CONFIGURATION condition, you'll get a half-built registry or an exception. Getting this wrong causes the dreaded "condition matches on some runs but not others" bug.

Transitively pulled dependencies

spring-boot-starter-data-jpa brings in (via POM):

• spring-boot-starter-jdbc → HikariCP, spring-jdbc
• hibernate-core
• spring-data-jpa
• spring-aspects (for @Transactional AOP)
• jakarta.persistence-api

Activated auto-configurations (in firing order)

1. DataSourceAutoConfiguration — class-level @ConditionalOnClass(DataSource.class) passes because spring-jdbc is on the classpath. Imports nested configs Hikari, Tomcat, Dbcp2, OracleUcp — but only Hikari matches because HikariCP is the only pool on the classpath.
2. JdbcTemplateAutoConfiguration — @AutoConfigureAfter(DataSourceAutoConfiguration.class). Creates JdbcTemplate and NamedParameterJdbcTemplate.
3. HibernateJpaAutoConfiguration — @AutoConfigureAfter({DataSourceAutoConfiguration.class, ...}). Creates EntityManagerFactory, picks Hibernate as the JPA provider.
4. JpaBaseConfiguration (imported by above) — creates JpaVendorAdapter, PersistenceManagedTypes, PlatformTransactionManager.
5. DataSourceTransactionManagerAutoConfiguration — backs off because JpaBaseConfiguration already registered a JpaTransactionManager (@ConditionalOnMissingBean(PlatformTransactionManager.class)).
6. TransactionAutoConfiguration — creates TransactionalOperator, enables @Transactional via ProxyTransactionManagementConfiguration.
7. JpaRepositoriesAutoConfiguration — scans for @Repository / JpaRepository interfaces, creates proxies.
8. DataSourceInitializationAutoConfiguration — runs schema.sql, data.sql if present.
9. SqlInitializationAutoConfiguration (Spring Boot 2.5+) — newer schema init mechanism with spring.sql.init.* properties.

Ordering guarantees

The critical ordering is DataSourceAutoConfiguration → HibernateJpaAutoConfiguration → JpaRepositoriesAutoConfiguration. This is enforced via @AutoConfigureAfter declarations, resolved at parse time by AutoConfigurationSorter using topological sort.

What you can verify

Run with --debug and search for "Positive matches". You'll see HibernateJpaAutoConfiguration with conditions like:

• @ConditionalOnClass found org.hibernate.SessionFactory
• @ConditionalOnSingleCandidate(DataSource.class) found exactly one
• @ConditionalOnMissingBean(JpaTransactionManager.class) did not find any

What commonly goes wrong

If you define your own DataSource bean but don't configure a JpaVendorAdapter, HibernateJpaAutoConfiguration still fires because @ConditionalOnMissingBean on its beans still matches. This can cause subtle bugs where you think you disabled JPA but you actually replaced only the pool. The fix is explicit exclusion: exclude = HibernateJpaAutoConfiguration.class.

The four breaking changes to handle

1. Registration file — Boot 2 uses spring.factories, Boot 3 uses AutoConfiguration.imports.
2. javax.* → jakarta.* — servlet, persistence, validation APIs all moved.
3. Minimum Java version — Boot 2.7 requires Java 8+; Boot 3 requires Java 17+.
4. @AutoConfiguration annotation — Boot 3 preferred, Boot 2.7+ also supports it.

Strategy 1 — dual-JAR (recommended)

Ship two separate artifacts:

• mylib-spring-boot-2-autoconfigure — uses spring.factories, javax.*
• mylib-spring-boot-3-autoconfigure — uses AutoConfiguration.imports, jakarta.*

Use Maven profiles or Gradle source sets to build both from a shared codebase with javax-to-jakarta substitution. This is how Hibernate 6 and Jackson ship dual artifacts.

Strategy 2 — single JAR with dual registration

Put the file in both locations:

project layoutsrc/main/resources/META-INF/
├── spring.factories                                                    # Boot 2
└── spring/
    └── org.springframework.boot.autoconfigure.AutoConfiguration.imports # Boot 3

Works because Boot 2 ignores the new file and Boot 3 prefers the new file but still reads the old. But you can only pick one of javax or jakarta — which forces you to pick a minimum Boot version.

Strategy 3 — runtime detection (advanced)

Use @ConditionalOnClass to branch between code paths that depend on jakarta.servlet.* vs javax.servlet.*. You'll need separate auto-config classes per namespace, each conditional on the presence of the right Servlet API. The starter then loads the correct one.

java@AutoConfiguration
@ConditionalOnClass(name = "jakarta.servlet.Servlet")
public class MyLibJakartaAutoConfiguration { ... }

@AutoConfiguration
@ConditionalOnClass(name = "javax.servlet.Servlet")
@ConditionalOnMissingClass("jakarta.servlet.Servlet")
public class MyLibJavaxAutoConfiguration { ... }

Compatibility matrix to publish

Starter version	Boot version	Java version
1.x	2.5 - 2.7	8+
2.x	3.0+	17+

Document this clearly and use semantic versioning — never bump the minor version when dropping Boot 2 support. Always bump major.

@AutoConfiguration in one sentence

A Spring Boot 3-introduced meta-annotation equivalent to @Configuration(proxyBeanMethods = false) + @AutoConfigureBefore + @AutoConfigureAfter, designed specifically for auto-configuration classes.

Full expansion

java — the annotation definition@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Configuration(proxyBeanMethods = false)
@AutoConfigureBefore
@AutoConfigureAfter
public @interface AutoConfiguration {
    @AliasFor(annotation = Configuration.class)
    String value() default "";
    Class<?>[] before() default {};
    String[]   beforeName() default {};
    Class<?>[] after() default {};
    String[]   afterName() default {};
}

Why proxyBeanMethods = false matters

By default, @Configuration uses proxyBeanMethods = true, meaning Spring wraps the configuration class in a CGLIB subclass. Inside this subclass, every @Bean method is intercepted so that calling serviceA() from within serviceB() returns the singleton instance, not a new invocation.

java@Configuration  // proxyBeanMethods = true by default
public class MyConfig {
    @Bean public Foo foo() { return new Foo(); }
    @Bean public Bar bar() { return new Bar(foo()); }
    // foo() here is intercepted — returns the singleton, not a new Foo
}

The cost of CGLIB proxies

• Class loading — CGLIB generates a new subclass at runtime for every @Configuration.
• Method interception overhead — every call to a @Bean method goes through the CGLIB callback.
• Reflection cost — no-args constructor must be public; the class can't be final.
• GraalVM hostility — CGLIB proxies require runtime bytecode generation, which native-image cannot do at build time.

Why auto-configs don't need it

Well-written auto-configs take dependencies via method parameters, not via inter-method calls:

java@AutoConfiguration   // proxyBeanMethods = false
public class MyAutoConfig {
    @Bean public Foo foo() { return new Foo(); }
    @Bean public Bar bar(Foo foo) { return new Bar(foo); }
    // bar() receives the singleton foo via parameter injection
}

Spring still wires foo correctly because it's resolved from the BeanFactory, not via method call.

Measured impact

The Spring team measured ~15% startup reduction when Spring Boot 2.2 switched internal auto-configs to proxyBeanMethods = false. That's why @AutoConfiguration bakes this default in — it's the right setting 99% of the time for auto-configs.

Diagnosis — step by step

1. Confirm the symptom — inject DataSource and log dataSource.getClass(). If it's HikariDataSource from Spring Boot config instead of their custom one, the backoff failed.
2. Run with --debug and search for DataSourceAutoConfiguration in the condition evaluation report. Look for:

   consoleDataSourceAutoConfiguration.PooledDataSourceConfiguration.Hikari matched:
      - @ConditionalOnMissingBean (types: javax.sql.DataSource) did not find any beans

   If this matches, Spring didn't see the custom bean — which means it wasn't registered yet when the auto-config ran.
3. Check /actuator/beans — look for the custom bean by name. Is it there at all? What's its configurationClass?

Root causes (from most to least common)

Cause 1 — custom bean is inside an auto-config, not user config

If the colleague registered the bean in a @Configuration class that's listed in AutoConfiguration.imports, both configs run as deferred imports. The ordering between them becomes undefined unless explicit @AutoConfigureBefore is used.

Fix: Move the bean to a user-level @Configuration class (scanned via component scan) — user configs always beat auto-configs due to DeferredImportSelector ordering.

Cause 2 — wrong bean type

The colleague defined a HikariDataSource bean, but @ConditionalOnMissingBean on the auto-config uses DataSource. Normally this would match, but if the custom bean has an @Qualifier or is annotated with @Primary, Spring's bean-matching logic may not see it as "missing".

Fix: Declare the bean as DataSource type explicitly in the @Bean method signature. Don't use HikariDataSource as the return type.

Cause 3 — lazy initialization hiding the problem

If spring.main.lazy-initialization=true, the order of @ConditionalOnMissingBean evaluation vs bean registration can become non-deterministic for certain edge cases.

Fix: Disable lazy init temporarily to confirm.

Cause 4 — factory bean indirection

If the custom DataSource is returned from a FactoryBean, @ConditionalOnMissingBean needs to resolve the factory's getObjectType() return type. For parameterized factory beans, this can fail.

Fix: Use @ConditionalOnMissingBean(ignoredType = "...") or declare the factory with a concrete type.

Cause 5 — multiple data sources

The colleague may have defined one DataSource, but some other auto-config (e.g. XADataSourceAutoConfiguration) is adding another. Spring Boot sees two DataSources and doesn't know which is primary.

Fix: Mark the custom bean with @Primary, or exclude XADataSourceAutoConfiguration.

The nuclear option

Exclude the auto-config entirely:

java@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)

This is correct if the colleague genuinely wants full control — but it also disables derived auto-configs like HibernateJpaAutoConfiguration's DataSource lookup, which can surprise downstream teams.

The fundamental shift

In the JVM world, Spring Boot discovers auto-configuration at runtime: it reads AutoConfiguration.imports, evaluates conditions dynamically, creates bean definitions via reflection, and uses CGLIB for proxies. Native image cannot do any of these at runtime — it's a closed-world, ahead-of-time compiled executable with no class loader, no reflection (unless registered), and no runtime bytecode generation.

Spring AOT's job

Spring 6 / Boot 3 introduced Spring AOT (spring-aot-processor), which runs during the Maven/Gradle build and generates equivalent ahead-of-time code. Specifically:

1. BeanFactoryInitializationAotContribution

AOT builds an in-memory ApplicationContext at build time, runs all the same condition evaluation logic, and captures the final set of bean definitions. This is then emitted as plain Java code:

generated at build time// target/spring-aot/main/sources/com/example/MyApp__BeanFactoryRegistrations.java
public class MyApp__BeanFactoryRegistrations implements BeanFactoryInitializer {
    @Override
    public void initialize(DefaultListableBeanFactory factory) {
        factory.registerBeanDefinition("dataSource",
            BeanDefinitionBuilder.rootBeanDefinition(HikariDataSource.class)
                .addPropertyValue("jdbcUrl", ...)
                .getBeanDefinition());
        // ... hundreds more
    }
}

2. Reflection hints

Every class accessed via reflection at runtime must be registered at build time. Spring AOT scans beans for:

• Constructor injection → register constructor for reflection
• @Autowired fields → register fields
• JPA entities → register all getters/setters
• Jackson-serialized DTOs → register constructors and accessors

These are emitted as reflect-config.json files under META-INF/native-image/.

3. Proxy hints

CGLIB proxies cannot be generated at runtime in native image. Spring AOT pre-generates JDK dynamic proxies (interface-based) during AOT processing and registers them. This is why @Configuration(proxyBeanMethods = true) is penalized heavily in AOT — it forces CGLIB which doesn't work natively.

4. Resource hints

application.properties, banner.txt, Thymeleaf templates, etc., are all registered in resource-config.json so GraalVM includes them in the executable.

What you lose in native mode

• No dynamic class loading — e.g. Class.forName("com.example.Plugin") at runtime fails unless pre-registered.
• No dynamic condition evaluation — conditions that depend on runtime environment (not @Profile — that's supported) don't work.
• No hot reload of beans — the bean factory is frozen at build time.
• Reduced debugging — no /actuator/conditions endpoint with runtime condition evaluation (though build-time report is available).

The payoff

• Startup: ~50ms vs 3-10s on JVM
• Memory: ~60-100MB RSS vs 300-500MB
• No warmup — peak throughput from first request
• Ideal for serverless (Lambda, Cloud Functions) where cold starts kill economics

The problem it solves

Imagine an auto-configuration class lives in a JAR under the package com.example.mylib, and your application's @SpringBootApplication is in com.example.app. @ComponentScan (which defaults to the app's base package) would only find app classes — not the library's auto-config. So far so good.

But what if a developer moves your auto-config under com.example (shared root package)? Now @ComponentScan will find it — in addition to the import via AutoConfiguration.imports. Result: the auto-config class is registered twice, and every @Bean method runs twice, causing BeanDefinitionOverrideException or worse, silent duplicate beans.

What AutoConfigurationExcludeFilter does

java — simplifiedpublic class AutoConfigurationExcludeFilter implements TypeFilter {

    @Override
    public boolean match(MetadataReader reader, MetadataReaderFactory factory) {
        return isConfiguration(reader) && isAutoConfiguration(reader);
    }

    private boolean isAutoConfiguration(MetadataReader reader) {
        return getAutoConfigurations().contains(reader.getClassMetadata().getClassName());
    }

    private List<String> getAutoConfigurations() {
        if (autoConfigurations == null) {
            autoConfigurations = ImportCandidates.load(AutoConfiguration.class, ...).getCandidates();
        }
        return autoConfigurations;
    }
}

It reads the full list of registered auto-configurations once and caches it. Then, during the @ComponentScan walk, any class that matches both "is a configuration" AND "is a registered auto-configuration" is excluded from scan results.

Why this only appears in @SpringBootApplication

If you write a plain Spring application with @ComponentScan manually, this filter isn't added. You wouldn't have auto-configurations either, so no conflict. The filter is a safety net specifically for the Spring Boot scenario where auto-configs exist and component scan runs on overlapping packages.

Practical takeaway

When writing a starter, name your auto-configure module's base package distinctly from your application's base package. Don't rely on AutoConfigurationExcludeFilter as an excuse to ignore package hygiene — it exists as defence in depth, not as the primary mechanism.

What relaxed binding is

A single Java field like apiUrl can be set from multiple sources using different naming conventions. Spring Boot's Binder API normalizes all of them before matching against the field.

The four sources

Source	Canonical form	Example	Notes
Properties file	kebab-case	mylib.api-url=x	Recommended
YAML file	camelCase or kebab	mylib:\n apiUrl: x	Both work
Environment variable	UPPER_SNAKE	MYLIB_API_URL=x	Only viable form
System property	any	-Dmylib.apiUrl=x	Dot-notation

How Binder normalizes names

When Spring Boot binds a property, it generates a ConfigurationPropertyName — a normalized representation. The algorithm:

1. Split on . → elements
2. For each element, split on case boundaries and - and _
3. Lowercase everything
4. Join with -

So MYLIB_API_URL, mylib.apiUrl, mylib.api-url, and mylib.API_URL all normalize to the same mylib.api-url and match the apiUrl field.

Indexed properties (the tricky part)

Collections and maps also bind:

yamlmylib:
  servers:
    - name: primary
      url: https://a.com
    - name: backup
      url: https://b.com

propertiesmylib.servers[0].name=primary
mylib.servers[0].url=https://a.com
mylib.servers[1].name=backup
mylib.servers[1].url=https://b.com

env varMYLIB_SERVERS_0_NAME=primary
MYLIB_SERVERS_0_URL=https://a.com

The env var form uses _INDEX_ instead of [N] because square brackets aren't allowed in shell env vars.

Validation with JSR-303

java@ConfigurationProperties(prefix = "mylib")
@Validated
public class MyLibProperties {
    @NotBlank
    private String apiUrl;

    @Min(100) @Max(30000)
    private int timeoutMs;

    @Valid
    private List<ServerConfig> servers;
}

Failures surface at startup with the full property path — e.g. mylib.servers[1].name: must not be blank. Compare this to @Value, which silently defaults or throws NPE at runtime. Always prefer @ConfigurationProperties for structured config.

Constructor binding (Spring Boot 2.2+)

java — immutable config@ConfigurationProperties(prefix = "mylib")
public record MyLibProperties(
    String apiUrl,
    @DefaultValue("5000") int timeoutMs,
    @DefaultValue("true") boolean enabled
) {}

Records + @ConstructorBinding (implicit in Boot 3) → immutable, no setters, no Lombok needed. This is the modern recommended form.

Step 0 — measure before optimizing

Always baseline first. Enable Spring Boot's startup tracking:

application.propertiesspring.jmx.enabled=true
management.endpoints.web.exposure.include=startup
management.endpoint.startup.enabled=true

Then GET /actuator/startup returns a hierarchical trace showing which beans took the longest to instantiate. You'll often find one or two culprits (Hibernate session factory, a large Liquibase migration, Kafka admin client).

Tier 1 — zero-code changes (5 min effort, 10-30% reduction)

1. Remove unused dependencies — every auto-config that fires is startup cost. Run mvn dependency:analyze.
2. Disable unused auto-configurations — exclude SecurityAutoConfiguration, WebSocketAutoConfiguration, etc. that you don't use.
3. Enable AppCDS — 20-40% reduction with zero code changes. Just generate the archive during image build.

Tier 2 — configuration tweaks (1 hour effort, 20-40% reduction)

1. Lazy initialization — spring.main.lazy-initialization=true. Warning: first request is slower, and startup-time errors become runtime errors.
2. Disable Hibernate validation on startup — spring.jpa.hibernate.ddl-auto=none, spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true.
3. Tune HikariCP — reduce minimum-idle. Initial pool warmup often adds 500ms-1s.
4. Defer Flyway/Liquibase — run migrations in a separate pipeline step instead of application startup.
5. Disable JMX endpoints — spring.jmx.enabled=false (if not using JMX).

Tier 3 — code changes (1-2 days effort, 30-50% reduction)

1. Replace @Configuration with @AutoConfiguration in internal starters — removes CGLIB overhead.
2. Reduce component scan surface — @SpringBootApplication(scanBasePackages = "com.myapp.api") instead of scanning everything.
3. Use @Lazy on expensive beans selectively — e.g. rarely-used integrations.
4. Replace reflection-heavy Jackson deserialization with afterburner module or blackbird.
5. Profile-guided optimization — with -XX:+UseParallelGC or -XX:TieredStopAtLevel=1 for startup.

Tier 4 — architectural change (1 week+ effort, 90%+ reduction)

GraalVM Native Image — compile to native executable with Spring AOT. Startup drops to <100ms, memory drops 60-80%. Costs: longer build times (5-15 min), more limited runtime reflection, some libraries incompatible.

When to stop optimizing

If you're deploying to a long-running container (Kubernetes deployment, not Lambda), 12s→6s is often not worth the effort. Spend that engineering time on HTTP response latency or database query optimization instead — those have customer-visible impact. Aggressive startup optimization matters most for: FaaS, autoscaled services with frequent cold starts, CI pipelines running many integration tests.

What's in the report

The ConditionEvaluationReport is the authoritative record of every auto-configuration decision Spring Boot made during startup. It contains four sections:

1. Positive matches — auto-configs that activated, with each condition that passed and why.
2. Negative matches — auto-configs that were skipped, with the specific failing condition.
3. Exclusions — auto-configs explicitly excluded via @SpringBootApplication(exclude=...) or spring.autoconfigure.exclude.
4. Unconditional classes — configs with no conditions (always loaded).

Development-time access

Run with --debug or set debug=true in application.properties. The report prints to stdout during startup.

Production access via Actuator

Expose the conditions endpoint:

application.propertiesmanagement.endpoints.web.exposure.include=conditions,health,info,metrics
management.endpoint.conditions.enabled=true

Then GET /actuator/conditions returns JSON:

json{
  "contexts": {
    "application": {
      "positiveMatches": {
        "DataSourceAutoConfiguration": [
          { "condition": "OnClassCondition",
            "message": "@ConditionalOnClass found 'javax.sql.DataSource'" }
        ],
        "DataSourceAutoConfiguration#dataSource": [
          { "condition": "OnBeanCondition",
            "message": "@ConditionalOnMissingBean (types: javax.sql.DataSource) did not find any beans" }
        ]
      },
      "negativeMatches": {
        "MongoAutoConfiguration": {
          "notMatched": [ { "condition": "OnClassCondition",
            "message": "did not find required class 'com.mongodb.MongoClient'" } ],
          "matched": []
        }
      }
    }
  }
}

Production use cases

• "Why isn't my bean being picked up?" — Search negative matches for the auto-config that should register it.
• Auditing which auto-configs are active — Compare between environments to spot drift.
• Understanding dependency bloat — Count positive matches. If you have 80+ auto-configs active and only use 20, there's cleanup to do.
• Diagnosing backoff failures — If a custom bean should have suppressed an auto-config but didn't, the positive-match entry will show @ConditionalOnMissingBean did not find any beans — telling you the user bean wasn't visible.

Security consideration

The /actuator/conditions endpoint leaks significant information about your application's structure (class names, property values, bean hierarchy). Never expose it on a public interface. Use Actuator security:

application.propertiesmanagement.server.port=9090
management.server.address=127.0.0.1
management.endpoints.web.exposure.include=conditions

Bind Actuator to a separate internal port and protect with network policy / Spring Security.

The ordering contract

Auto-configurations form a directed dependency graph where edges represent "must be parsed before/after". AutoConfigurationSorter performs a topological sort of this graph during AutoConfigurationImportSelector.getAutoConfigurationEntry(), producing a linear ordering respected by Spring's configuration parser.

The algorithm

1. For each auto-config, extract its @AutoConfigureBefore, @AutoConfigureAfter, and @AutoConfigureOrder metadata from annotations.
2. Also extract relationships from @AutoConfiguration(before = ..., after = ...) — these are equivalent.
3. Build a directed graph:
   • @AutoConfigureBefore(B.class) on A → edge A → B (A processed first)
   • @AutoConfigureAfter(B.class) on A → edge B → A (A processed after)
4. Apply @AutoConfigureOrder as a secondary sort key — lower values first.
5. Perform Kahn's algorithm topological sort.
6. If inDegree[node] > 0 remains for any node after visiting all reachable nodes, a cycle exists.

What happens on a cycle

AutoConfigurationSorter throws IllegalStateException at startup with the cycle path:

stack tracejava.lang.IllegalStateException: AutoConfigure cycle detected between
  ConfigA -> ConfigB -> ConfigC -> ConfigA
    at AutoConfigurationSorter.sort(AutoConfigurationSorter.java:72)

The application refuses to start. This is a hard failure — you must break the cycle. In practice, cycles almost always happen when two starters from different vendors over-specify ordering. The fix is usually to remove one of the @AutoConfigureBefore/@AutoConfigureAfter declarations.

@AutoConfigureOrder — the weaker mechanism

Uses an integer priority (default Ordered.LOWEST_PRECEDENCE). It's a secondary tiebreaker:

java@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
@AutoConfiguration
public class SecurityAutoConfiguration { ... }

Security auto-configs typically use HIGHEST_PRECEDENCE so they run first — useful when they don't have a natural after relationship to depend on.

Why ordering matters for conditions

Consider:

java@AutoConfiguration(after = RedisAutoConfiguration.class)
public class CacheAutoConfiguration {
    @Bean @ConditionalOnBean(RedisTemplate.class)
    public CacheManager redisCacheManager(RedisTemplate template) { ... }
}

If CacheAutoConfiguration ran before RedisAutoConfiguration, RedisTemplate wouldn't exist yet in the BeanFactory, and @ConditionalOnBean would fail. @AutoConfigureAfter enforces the correct ordering.

Internal representation of ordering

Spring Boot 3 reads ordering metadata from a compiled META-INF/spring/...AutoConfiguration.annotation.imports file when available, avoiding reflection on each class. This is generated by the spring-boot-autoconfigure-processor annotation processor during compilation — another startup-time optimization.

spring.factories — the legacy format

META-INF/spring.factoriesorg.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.example.FooAutoConfiguration,\
  com.example.BarAutoConfiguration

org.springframework.context.ApplicationContextInitializer=\
  com.example.MyInitializer

org.springframework.boot.diagnostics.FailureAnalyzer=\
  com.example.MyFailureAnalyzer

A single file that hosts many different extension points — all keyed by the fully-qualified interface name they extend. Parsed by SpringFactoriesLoader.loadFactoryNames() using Properties-style key-value parsing.

AutoConfiguration.imports — Boot 3's dedicated file

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.importscom.example.FooAutoConfiguration
com.example.BarAutoConfiguration

One file per extension point. The filename is the interface name. Format is dead simple: one FQN per line, # comments, no quoting.

Why the change — five reasons

1. Parse performance — ImportCandidates reads one line at a time with BufferedReader. No Properties parsing, no key splitting, no line-continuation handling. Measured ~10x faster on cold JVM start for projects with many dependencies.
2. Less error-prone — spring.factories's backslash continuation is notoriously fragile. Forget a backslash? Half your auto-configs silently don't register. The new format has no escape mechanism to get wrong.
3. Better IDE / tooling support — each extension has its own file, so IDE plugins can validate "this line must be a class that implements X". Possible with spring.factories but nobody built it.
4. Enables indexed imports — Spring Boot can write a compiled index at build time (spring-boot-autoconfigure-processor) listing classes in dependency order. The new format makes this indexing trivial.
5. Multi-module clarity — with one file per concern, it's obvious from a JAR's contents which extensions it contributes. spring.factories required reading the file to know.

Backward compatibility

Spring Boot 3 still reads spring.factories, but only for non-auto-config extensions — ApplicationListener, FailureAnalyzer, etc. For auto-configs specifically, spring.factories entries are ignored in Boot 3. This caught many library authors off-guard during migration; Boot 3 even emits a deprecation warning when it finds auto-config entries in spring.factories.

Migration rule

If you ship a Boot 2 starter:

• Boot 2 support: keep spring.factories
• Boot 3 support: add META-INF/spring/...AutoConfiguration.imports
• Ship both in a dual-JAR or as separate version lines.

Other extension points that moved

Boot 3 introduced several per-interface imports files under META-INF/spring/:

• org.springframework.boot.env.EnvironmentPostProcessor.imports
• org.springframework.boot.BootstrapRegistryInitializer.imports
• org.springframework.context.ApplicationContextInitializer.imports

The pattern is uniform — expect more extension points to migrate in future Boot versions.

Short answer

Yes, they can — and this happens frequently. The resolution mechanism depends on whether the beans are mutually exclusive (only one should win) or complementary (both should coexist with different names/roles).

Case 1 — mutually exclusive (only one wins)

Example: DataSourceAutoConfiguration imports nested configurations for Hikari, Tomcat JDBC, DBCP2, and Oracle UCP. Each registers a DataSource bean. Conflict is resolved by class-level @ConditionalOnClass:

java — DataSourceAutoConfiguration internal@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(HikariDataSource.class)
@ConditionalOnMissingBean(DataSource.class)
@ConditionalOnProperty(name = "spring.datasource.type",
                       havingValue = "com.zaxxer.hikari.HikariDataSource",
                       matchIfMissing = true)
static class Hikari { ... }

@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(org.apache.tomcat.jdbc.pool.DataSource.class)
@ConditionalOnMissingBean(DataSource.class)
@ConditionalOnProperty(name = "spring.datasource.type",
                       havingValue = "org.apache.tomcat.jdbc.pool.DataSource")
static class Tomcat { ... }

Three conditions work together: "pool class on classpath" AND "no DataSource already defined" AND "property matches (or is unset for default)". Only the first one to match wins — subsequent ones see a DataSource already registered and back off via @ConditionalOnMissingBean.

Case 2 — two different auto-configs, both want to register the same type

Example: DataSourceTransactionManagerAutoConfiguration wants to register a PlatformTransactionManager, and so does JpaBaseConfiguration. Resolution:

• Ordering: @AutoConfigureAfter(DataSourceTransactionManagerAutoConfiguration.class) on JPA config.
• When JPA runs, it checks @ConditionalOnMissingBean(PlatformTransactionManager.class) — finds the JDBC one registered already.
• Wait — JPA actually replaces it. The JPA config uses a higher-priority registration trick: it registers a JpaTransactionManager with @Primary or uses @ConditionalOnSingleCandidate to coexist.

In practice, the Spring team ordered these carefully: DataSourceTransactionManagerAutoConfiguration uses @ConditionalOnMissingBean(PlatformTransactionManager.class), and JPA registers its bean first in the ordering. So the JDBC one is skipped entirely.

Case 3 — two auto-configs from different JARs

Say spring-boot-starter-cache registers a CacheManager, and spring-boot-starter-data-redis also registers one. The resolution depends on:

1. Ordering (@AutoConfigureBefore/@AutoConfigureAfter) — determines who goes first.
2. @ConditionalOnMissingBean — whoever goes second yields.
3. @ConditionalOnProperty — often used to let users explicitly choose (e.g. spring.cache.type=redis).

Case 4 — duplicate bean definition without conditions (pathological)

If two auto-configs register the same bean name with no conditions to guard against it, you get BeanDefinitionOverrideException at startup (Boot 2.1+). You can disable this check with spring.main.allow-bean-definition-overriding=true — but don't. It's there to catch genuine bugs. If you need one config to win, use @Primary or explicit exclusion.

The golden rules

1. Always pair @Bean in an auto-config with @ConditionalOnMissingBean.
2. Name your beans explicitly (don't rely on method name) to avoid accidental collision.
3. Use @ConditionalOnProperty for mutually-exclusive variants.
4. Declare ordering with @AutoConfigureBefore/@AutoConfigureAfter when the resolution depends on timing.

The scale of the problem

A typical Spring Boot 3 application with common dependencies has 150-200 candidate auto-configurations. Most are irrelevant to your app (MongoDB, Cassandra, Elasticsearch, RabbitMQ, etc.). If Spring evaluated each one individually — parsing its annotations, resolving its conditions, inspecting its @Bean methods — startup would take minutes.

The optimization — two-step bulk filtering

OnClassCondition implements two interfaces:

1. Condition — normal condition evaluation, called per bean/config.
2. AutoConfigurationImportFilter — a bulk filter called once with all candidates.

The AutoConfigurationImportFilter interface lets Spring Boot ask one condition class: "given this list of 200 candidate auto-configs, which ones pass your check?" — in a single pass, using batch-optimized logic.

How it works internally

java — simplifiedpublic class OnClassCondition extends FilteringSpringBootCondition {

    @Override
    protected ConditionOutcome[] getOutcomes(
            String[] autoConfigurationClasses,
            AutoConfigurationMetadata metadata) {

        // Metadata is pre-compiled at build time:
        // it contains the @ConditionalOnClass value for each autoconfig
        // without needing to load the class itself.

        ConditionOutcome[] outcomes = new ConditionOutcome[autoConfigurationClasses.length];
        for (int i = 0; i < autoConfigurationClasses.length; i++) {
            String className = autoConfigurationClasses[i];
            String onClass = metadata.get(className, "ConditionalOnClass");
            if (onClass != null) {
                if (!classPresent(onClass)) {
                    outcomes[i] = ConditionOutcome.noMatch(...);
                }
            }
        }
        return outcomes;
    }
}

Crucially: it reads the @ConditionalOnClass target from pre-compiled metadata — it never loads the auto-config class. Only candidates that pass are then handed to Spring for full annotation processing.

The metadata file

Spring Boot ships META-INF/spring-autoconfigure-metadata.properties, generated at build time by spring-boot-autoconfigure-processor:

spring-autoconfigure-metadata.propertiesorg.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration.ConditionalOnClass=\
  com.mongodb.MongoClient

org.springframework.boot.autoconfigure.cassandra.CassandraAutoConfiguration.ConditionalOnClass=\
  com.datastax.oss.driver.api.core.CqlSession

So checking "is MongoDB on the classpath?" becomes a single Class.forName() attempt per auto-config, evaluated before any class is loaded.

Parallel evaluation (Spring Boot 2.5+)

If there are more than a threshold (~64) candidates, OnClassCondition splits the work across two threads — each checks half the candidates in parallel. This halves the classpath-scan latency on cold start. You can see this in OnClassCondition.getOutcomes() where it chooses between serial and parallel execution paths.

Measured impact

Without this optimization, a 200-candidate startup would:

• Load each auto-config class (reflection + class init) → ~200 class loads
• Evaluate each @Bean method's conditions individually
• Fall through to @ConditionalOnMissingBean which requires a BeanFactory lookup

With the optimization, 80%+ of candidates are eliminated in a single ~50ms pass before any class loading. Net startup impact: 1-3 seconds saved on a typical app.

Why this matters for library authors

When writing a custom starter, if you annotate your auto-config with @ConditionalOnClass(MyLibraryClass.class), run the spring-boot-autoconfigure-processor annotation processor to generate the metadata file:

xml — pom.xml<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure-processor</artifactId>
    <optional>true</optional>
</dependency>

Without it, Spring has to fall back to reading annotations at runtime — losing the bulk-filter optimization for your starter specifically. This is a common oversight in community starters.