Spring Boot config validation: separate valid syntax from a safe relay setting

Two separate failures

The RelaySettings record binds an int batchSize and a Duration timeout. Its batch size has a 1..100 constraint. A command-line value of zero causes context startup to fail; the test asserts failure rather than allowing a worker to run with no useful batch. A file containing 750ms binds Duration.ofMillis(750), which avoids an implicit unit guess.

The file tests check only accepted values. They do not yet test a corrupt file, a missing required key when a programmatic default is removed, an unknown property or a secret source outage. File loading and precedence happen before the final bean is judged.

Treat a restart as a configuration change

A 100-row upper bound is a validity guard, not a load-test result. The service can still overload a small database with a value inside the allowed range. Roll out a changed batch size with queue-age, connection-wait and tick-duration observations. If the value is rejected, the process should remain unready rather than starting a worker with a guessed fallback.

Config values must not appear in failure reports when they are credentials. Keep the typed bean small and avoid using a secret as an exception message. Readiness checks apply once startup succeeds; they do not repair a failed bind.

Checked source

@Validated
@ConfigurationProperties("relay")
record RelaySettings(@Min(1) @Max(100) int batchSize,
                     @NotNull Duration timeout) { }
assertThrows(RuntimeException.class,
    () -> app().run("--relay.batch-size=0"));

Verification boundary

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

Costs and limits

The fixture checks one invalid integer and explicit Duration units. It does not prove every configuration key, secret source, mount failure or operational capacity limit.

Common Mistakes

• Do not confuse a parseable value with an acceptable operating point.
• Do not silently replace an invalid operator value with a default.
• Do not expose secret values in binding diagnostics.

Read next

Spring Boot external config file: bind the value the process actually loads, Spring Boot configuration validation: reject an unusable relay before work starts, Spring Boot readiness health group: withdraw traffic on a required dependency failure, Spring Boot configuration sources: test each deployment path, not a guessed order.