Spring Boot configuration-property scanning: keep the package boundary explicit

Locate the scanned package

A receipt retry policy record lives in a library package while the application class sits under another root. A no-argument ConfigurationPropertiesScan scans from the annotated class package, so the library record may not be registered. Name a class in the library package through basePackageClasses or register the type explicitly with EnableConfigurationProperties. The class reference survives package renaming better than a string literal. Property binding] then validates the values that reached the bean.

Do not confuse two scanners

Component scanning finds component stereotypes. Configuration-property scanning finds eligible ConfigurationProperties classes but skips classes that are also components. Register a given configuration type through one clear path; duplicate registration can create confusing bean names and injection ambiguity. A third-party object that you cannot annotate may be bound through a ConfigurationProperties bean method. The component-scan boundary] explains why importing a module does not automatically discover all its classes.

Check the packaged module

A test in the application module may see the property record because test configuration imports it, while the final packaged service does not. Start the packaged application with a nondefault receipt retry count and assert the bound bean sees exactly that number. Then remove the required value and assert validation fails. That detects both an absent scan and an unintended fallback default.

Implementation contract

@SpringBootApplication
@ConfigurationPropertiesScan(basePackageClasses = ReceiptRetryProperties.class)
class ReceiptApplication {}

// ReceiptRetryProperties lives in the library package selected above.
@ConfigurationProperties(prefix = "receipt.retry")
record ReceiptRetryProperties(int maxAttempts, Duration backoff) {}

Cost and verification

Scanning a narrow package limits startup class inspection. The main risk is silent omission or duplicate registration, which a packaged-context test catches.

Common Mistakes

• Do not assume the application root covers a sibling library package.
• Do not annotate one properties type as both a scanned configuration type and a component without intent.
• Do not rely on a test-only import to prove packaged discovery.

Read next

Spring Boot configuration properties: bind values and reject bad startup input, Spring @Component versus @Bean: choose who constructs the dependency, Spring Boot config validation: separate valid syntax from a safe relay setting, Spring Boot configuration validation: reject an unusable relay before work starts, Spring Boot condition report: locate the missing auto-configuration decision.