Spring Boot configuration validation: reject an unusable relay before work starts

Fail at binding

The RelaySettings record carries @Min(1), @Max(100) and @NotNull constraints. The test passes --relay.batch-size=0 over a valid default. Context creation throws a runtime startup failure; the failure analysis names the command-line property origin and the minimum constraint. No scheduler starts in this small configuration context.

The test checks the invalid effective value, not a controller request. A bad setting should fail before the worker claims events. The precedence lesson explains how the invalid command-line value wins. Existing configuration material covers typed binding more generally.

What one constraint misses

Min and max protect only the numeric range. They do not prove that batch size 100 fits connection-pool capacity, that timeout matches a service objective, or that a secret points to a trusted endpoint. Validate cross-field invariants where needed and exercise them in a startup test. Keep the error message useful without printing a secret value.

The fixture has no external database or broker. A successfully bound configuration does not mean dependencies are ready. Readiness is a separate operational signal after startup.

Checked source

@Validated
@ConfigurationProperties("relay")
record RelaySettings(@Min(1) @Max(100) int batchSize,
                     @NotNull Duration timeout) { }

Verification boundary

BootRelaySettingsTest.invalidEffectiveBatchSizePreventsStartup. The excerpt is shortened or a labelled design sketch; the kit contains the checked tests.

Costs and limits

One invalid command-line batch size is checked. No full environment matrix, secret binding, cross-field rule or deployed health check is included.

Common Mistakes

• Do not silently clamp an invalid operator value.
• Do not treat successful binding as dependency readiness.
• Do not leak secret values in startup errors.

Read next

Spring Boot command-line properties: test the effective value at startup, Spring Boot Duration binding: make timeout units explicit, Spring readiness: report an unavailable dependency without forcing liveness failure, Spring Boot configuration properties: bind values and reject bad startup input.

Checked config-data continuation

Continue with Spring Boot configtree validation: reject a present but unsafe value.