Spring Boot ConditionalOnMissingBean: a default that yields to application code

The condition sees definitions so far

A shared receipt starter supplies a default ReceiptGateway, but one application needs a signed gateway. @ConditionalOnMissingBean can skip the default when a compatible application bean is already registered. Put this condition in auto-configuration, which is processed after user bean definitions, rather than scattering it among ordinary application configurations whose ordering may surprise you. Auto-configuration selects a default; @Primary merely chooses among beans that both exist.

Publish the integration contract

The auto-configuration class must be registered through the starter's auto-configuration imports resource. Declare a concrete return type that allows the condition to see the bean's intended API. A broad Object return type or a factory whose type cannot be predicted can produce an unexpected default. Test the starter in isolation and with a user ReceiptGateway implementation; the first case must create exactly one gateway, the second must leave the user's bean in place.

Do not hide configuration failure

A missing required signing key is not a reason to silently instantiate an insecure fallback. Conditional creation answers whether a bean is already supplied; property validation answers whether the chosen gateway can start safely. Startup validation should fail for invalid settings. Inspect the condition outcome when a bean is unexpectedly present, and keep any override behavior explicit in release notes and context tests.

Implementation contract

@AutoConfiguration
class ReceiptGatewayAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean(ReceiptGateway.class)
    ReceiptGateway receiptGateway(ReceiptGatewayProperties settings) {
        return new HttpReceiptGateway(settings.endpoint());
    }
}

Cost and verification

Condition evaluation occurs at startup, with negligible request-path cost. Maintaining a starter adds a compatibility obligation: changes to the default type or condition can alter which bean applications receive during an upgrade.

Common Mistakes

• Do not use a missing-bean condition in arbitrary user configuration and depend on incidental processing order.
• Do not return Object from a factory when the condition needs a predictable gateway type.
• Do not use a fallback bean to conceal invalid required credentials or endpoint settings.

Read next

Spring Boot auto-configuration: conditions and user-defined beans, Spring Boot auto-configuration: register imports and let a user bean win, Spring @Primary and @Qualifier: default selection versus an explicit bean, Spring Boot configuration validation: reject an unusable relay before work starts, Spring Boot ConditionalOnProperty: make optional infrastructure opt in.

Related Boot contract

Spring Boot condition report: locate the missing auto-configuration decision.