How does Spring Boot decide the order of auto-configurations?

How does Spring Boot decide the order of auto-configurations?

Spring Boot’s auto-configuration order looks magical from the outside, but internally it follows a very deterministic algorithm based on class loading, conditions, and ordering metadata.

Once you understand this, auto-configuration stops being “black magic” and becomes a rule-based system.

1. The Big Picture

Spring Boot does not randomly load auto-configurations.

It follows this pipeline:

Read metadata → Sort → Apply conditions → Instantiate

Image

Image

Image

2. Step 1 – Where Auto-Configs Come From

All auto-configurations are discovered from:

META-INF/spring.factories

Inside Spring Boot jars:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
DataSourceAutoConfiguration,\
WebMvcAutoConfiguration,\
SecurityAutoConfiguration,...

So initially:

They are just a list of class names.

No beans yet. No logic yet.

3. Step 2 – Ordering Rules (This Is the Core)

Spring applies three layers of ordering:

3.1 Explicit Ordering Annotations

Auto-configs can declare:

@AutoConfigureBefore(X.class)
@AutoConfigureAfter(Y.class)
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)

This creates a directed graph:

A -> B -> C

Spring topologically sorts this.

If there’s a cycle:

Spring throws an exception and aborts startup.

3.2 @Order (Secondary)

@Order(1)
public class WebMvcAutoConfiguration

Lower number = higher priority.

Used when:

No explicit before/after exists.

3.3 Default Classpath Order

If no ordering info:

JVM classpath loading order is used.

Which means:

  • JAR loading order
  • OS file system order

This is why:

Some bugs appear only in Docker but not locally.

4. Step 3 – Conditions Decide Whether, Not When

After ordering, Spring checks:

  • @ConditionalOnClass
  • @ConditionalOnMissingBean
  • @ConditionalOnProperty
  • @ConditionalOnWebApplication

Example:

@ConditionalOnClass(DataSource.class)
public class DataSourceAutoConfiguration

If condition fails:

That auto-config is skipped completely.

But ordering is already decided before this.

5. Step 4 – Bean Registration Order

Inside each auto-config:

@Bean
public DataSource dataSource()

Beans are registered in:

The same order as auto-config classes.

So final sequence is:

AutoConfig order → Bean method order → BeanPostProcessors

6. Why Order Matters So Much

Because of this:

@ConditionalOnMissingBean

If A runs before B:

  • B sees bean from A
  • B does nothing

If B runs before A:

  • B creates default
  • A backs off

Same code, totally different system.

7. Real Example: DataSource

Order:

  1. DataSourceAutoConfiguration
  2. DataSourceTransactionManagerAutoConfiguration
  3. JpaRepositoriesAutoConfiguration

Why?
Because:

JPA needs transaction manager
Transaction manager needs datasource

This is encoded via:

@AutoConfigureAfter(DataSourceAutoConfiguration.class)

8. Debug Mode: See the Real Order

Run with:

--debug

Spring prints:

Positive matches:
-----------------
DataSourceAutoConfiguration matched
WebMvcAutoConfiguration matched

Negative matches:
-----------------
SecurityAutoConfiguration did not match

This shows:

  • Final resolved order
  • Which ones applied
  • Which ones skipped

This is the single most powerful Spring Boot flag.

9. Internally: The Exact Algorithm

Simplified pseudo-flow:

1. Load all EnableAutoConfiguration classes
2. Build dependency graph (before/after)
3. Topological sort
4. Apply @Order
5. Apply classpath fallback
6. Evaluate conditions
7. Register beans

So ordering is resolved before any beans exist.

10. How Custom Auto-Configs Plug In

If you write your own starter:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
MyAutoConfiguration

You can control its position:

@AutoConfigureAfter(DataSourceAutoConfiguration.class)

This is how:

  • Kafka starter
  • Redis starter
  • Security starter

All integrate cleanly.

11. The 5 Most Common Ordering Bugs

Bug Root cause
Bean overridden unexpectedly Wrong @AutoConfigureAfter
Default bean created Custom config loaded too late
Missing transaction Tx auto-config ran before datasource
Security blocking everything Security auto-config ran too early
Works locally, fails in prod Classpath order difference

12. Why Spring Boot Rarely Breaks

Because auto-configs are written with:

  • Defensive ordering
  • Conservative conditions
  • Back-off logic
  • No hard assumptions

So even with 200 starters:

They usually self-organize correctly.

That’s the real engineering genius.

Interview-Grade Answer (For You, Nimai)

“Spring Boot decides auto-configuration order by first loading all EnableAutoConfiguration classes from spring.factories, then applying @AutoConfigureBefore/@After and @AutoConfigureOrder annotations to build a dependency graph. It topologically sorts this graph, applies @Order as a secondary rule, and finally falls back to classpath order. After ordering, conditional annotations decide which auto-configurations are actually applied.”

This answer puts you in the architect-level bracket.

Final Mental Model

Think of Spring Boot auto-config as:

A dependency-sorted plugin system.

Not magic.
Not reflection chaos.
Just a very well-designed graph solver.

Tags:

Leave a Reply