Spring Boot optional config import: know which default survives

The checked fallback

BootRelaySettingsTest prefixes an absent file URI with optional:. The context starts and RelaySettings reports the declared defaults: batch size 8 and timeout 2s. Those values are not proof that the file was loaded. The test chooses absence on purpose and asserts the fallback state.

For a local developer override, optional behavior can be useful. For a production-required endpoint or credential, it can hide a broken mount. The required import makes that failure visible. Decide per setting; do not apply optional: to an entire configuration path as a reflex.

Make a fallback observable

An operator should be able to tell whether the optional source was present without exposing secret values. Report a source-availability signal or a redacted effective setting. If the default is unsafe for production, reject startup with typed validation or a deployment-specific requirement.

This fixture has one absent file and programmatic defaults. It does not test partially written files, permission errors or simultaneous environment and CLI overrides. The source matrix separates those combinations.

Checked source

String missing = configDirectory.resolve("missing.properties").toUri().toString();
try (var context = app().run(
    "--spring.config.import=optional:" + missing)) {
    assertEquals(8, context.getBean(RelaySettings.class).batchSize());
}

Verification boundary

BootRelaySettingsTest.optionalMissingImportKeepsTheDeclaredDefaults. The excerpt is shortened; the source kit contains the checked fixture.

Costs and limits

The fallback is checked for one local missing file. It does not establish that any other optional source is safe to omit in production.

Common Mistakes

• Do not interpret a valid default as evidence that an import succeeded.
• Do not make a required secret optional.
• Do not hide the source of an effective value from operators.

Read next

Spring Boot config import: fail startup when a required file is missing, Spring Boot external config file: bind the value the process actually loads, Spring Boot configuration sources: test each deployment path, not a guessed order, Spring Boot configuration validation: reject an unusable relay before work starts.

Release boundary continuation

Continue with Spring Boot relative config imports: resolve from the declaring file.