BeanDefinitionOverrideException in Boot 3

Overview

In Spring Boot 2.x, defining two beans with the same name caused the second to silently replace the first — a behavior that could hide serious misconfiguration. Spring Boot 3 disables this by default, converting silent overrides into a hard startup failure: BeanDefinitionOverrideException. This is a deliberate safety improvement that surfaces hidden bean conflicts during migration or when library auto-configurations clash with application beans.

1. 01

   Rename the conflicting bean with a unique, descriptive name (preferred: always the first option).

2. 02

   Use @ConditionalOnMissingBean so your custom bean is only registered if no other bean of that type exists.

3. 03

   Use @Primary to signal which bean should be injected by default when multiple candidates exist.

4. 04

   Add @Qualifier to injection sites to select a specific bean by name.

5. 05

   Setting spring.main.allow-bean-definition-overriding=true restores Boot 2 behavior but is a last resort — it re-enables silent overrides.

// ❌ CONFLICT — two beans named 'dataSource' at startup
class="hi-ann">@Configuration
public class AppConfig {
    class="hi-ann">@Bean
    public DataSource dataSource() { // Name: "dataSource"
        return new HikariDataSource(hikariConfig());
    }
}

// ✅ FIX 1: Unique naming
class="hi-ann">@Configuration
public class AppConfig {
    class="hi-ann">@Bean("appDataSource")
    public DataSource dataSource() { ... }
}

// ✅ FIX 2: @ConditionalOnMissingBean (Library-safe override pattern)
class="hi-ann">@Configuration
public class AppConfig {
    class="hi-ann">@Bean
    class="hi-ann">@ConditionalOnMissingBean(DataSource.class) // Only register if nothing else provides one
    public DataSource dataSource() { ... }
}

// ✅ FIX 3: @Primary (Preferred injection candidate)
class="hi-ann">@Bean
class="hi-ann">@Primary
public DataSource primaryDataSource() { ... }

class="hi-ann">@Bean("secondaryDataSource")
public DataSource secondaryDataSource() { ... }

// Injection uses @Primary automatically:
// @Autowired DataSource ds; → gets primaryDataSource

// ⚠️ ESCAPE HATCH (Boot 2 compatibility only — avoid in new code)
# application.properties
spring.main.allow-bean-definition-overriding=true

1. 01

   Never use spring.main.allow-bean-definition-overriding=true in new projects — it trades a startup error for a silent runtime misconfiguration.

2. 02

   Prefer @ConditionalOnMissingBean in all shared library configurations to make them override-safe by design.

3. 03

   Add a startup smoke test to your CI pipeline that verifies ApplicationContext loads successfully — catches bean conflicts before they reach production.

What causes BeanDefinitionOverrideException in Boot 3 in Spring Boot 3?

Multiple @Configuration classes are producing @Beans with the same name — either because the application defines a bean that conflicts with a library's auto-configured bean, or because two configurations in a large codebase accidentally share a bean name. Spring Boot 3's stricter default makes this an application startup failure rather than a silent runtime surprise.

How do I fix BeanDefinitionOverrideException in Boot 3?

Rename the conflicting bean with a unique, descriptive name (preferred: always the first option). Use @ConditionalOnMissingBean so your custom bean is only registered if no other bean of that type exists. Use @Primary to signal which bean should be injected by default when multiple candidates exist. Add @Qualifier to injection sites to select a specific bean by name. Setting spring.main.allow-bean-definition-overriding=true restores Boot 2 behavior but is a last resort — it re-enables silent overrides.

Best practice #1 for preventing Spring Context · Boot 3 errors?

Never use spring.main.allow-bean-definition-overriding=true in new projects — it trades a startup error for a silent runtime misconfiguration.

Best practice #2 for preventing Spring Context · Boot 3 errors?

Prefer @ConditionalOnMissingBean in all shared library configurations to make them override-safe by design.

Best practice #3 for preventing Spring Context · Boot 3 errors?

Add a startup smoke test to your CI pipeline that verifies ApplicationContext loads successfully — catches bean conflicts before they reach production.