Spring Boot config import: fail startup when a required file is missing

The missing-file test

BootRelaySettingsTest points spring.config.import at a file URI that does not exist. The non-web Boot context fails before a RelaySettings bean can run. The test does not assert a specific outer exception class because Boot wraps the missing-location cause while constructing the application.

This policy fits a setting that must come from deployment state. If the application silently falls back to an old batch size or stale endpoint, it may process work with the wrong assumptions. The optional case deliberately chooses different behavior. Document which imports are mandatory and check that the intended path is mounted before rollout.

Do not put secrets into diagnostics

A location error may reveal the path, while binding errors can reveal a rejected value. Avoid putting credentials in command-line arguments or startup logs. A missing secret import should prevent a service from accepting traffic, but the error page should not include a credential.

The test proves a missing local file is rejected. It does not verify a readable file that contains a wrong key, wrong permissions, a rotated secret, or the availability of a remote configuration service. Typed validation handles the value after a source is loaded.

Checked source

String missing = configDirectory.resolve("missing.properties").toUri().toString();
assertThrows(RuntimeException.class,
    () -> app().run("--spring.config.import=" + missing));

Verification boundary

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

Costs and limits

The test uses an absent file in a local temporary directory. It does not measure a deployment volume or a remote config source, and it does not inspect secret handling.

Common Mistakes

• Do not mark a mandatory import optional merely to clear a startup failure.
• Do not confuse a missing file with a present file containing an invalid value.
• Do not print imported secrets in startup diagnostics.

Read next

Spring Boot optional config import: know which default survives, Spring Boot config validation: separate valid syntax from a safe relay setting, Spring Boot profile files: bind only the selected environment override, Spring readiness: report an unavailable dependency without forcing liveness failure.

Checked process continuation

Continue with Spring Boot required import: fail when a relative file is missing.