Spring Boot Configuration Precedence Order Explained
Learn the order in which Spring Boot reads configuration: command line, environment, profile files, application files and defaults.

You set app.greeting=hello in application.yaml, deploy, and the endpoint answers hola. Somewhere another source defines the same property and wins. Spring Boot reads configuration from around seventeen places, and when two define the same key, a fixed order decides. Knowing that order turns "why is this value wrong in staging" from an hour of grep into a question you can answer with one request. This post gives the order, runs one property through several sources to show the winner changing, covers how environment variable names map onto properties, how profiles and external files fit in, and the endpoint that shows which source supplied a value. Examples use Spring Boot 4.
The order, highest first
A higher entry overrides a lower one for the same property. The list below is the part of the order you will meet in real projects; the complete table is in the externalized configuration reference.
| Priority | Source | Example |
|---|---|---|
| 1 | Command-line arguments | --app.greeting=cli |
| 2 | SPRING_APPLICATION_JSON | {"app":{"greeting":"json"}} |
| 3 | Java system properties | -Dapp.greeting=sysprop |
| 4 | OS environment variables | APP_GREETING=env |
| 5 | Profile-specific files outside the jar | ./config/application-prod.yaml |
| 6 | Profile-specific files inside the jar | classpath:application-prod.yaml |
| 7 | Application files outside the jar | ./config/application.yaml |
| 8 | Application files inside the jar | classpath:application.yaml |
| 9 | @PropertySource on configuration classes | @PropertySource("classpath:extra.properties") |
| 10 | Default properties | SpringApplication.setDefaultProperties |
In tests, @TestPropertySource and the properties attribute of @SpringBootTest sit above all of these. The mnemonic: the more deliberate and closer to the launch, the higher the priority. A command-line flag beats everything you baked into the jar, which is the point, because it lets operations override what developers shipped.
A concrete case
Make a property visible, then add sources one by one.
@RestController
class GreetingController {
private final String greeting;
GreetingController(@Value("${app.greeting:unset}") String greeting) {
this.greeting = greeting;
}
@GetMapping("/greeting")
String greeting() {
return greeting;
}
}app:
greeting: file-in-jarNow run it five ways and read the answer each time:
java -jar target/shop.jar
curl -s localhost:8080/greeting # file-in-jar
APP_GREETING=env java -jar target/shop.jar
curl -s localhost:8080/greeting # env
APP_GREETING=env java -Dapp.greeting=sysprop -jar target/shop.jar
curl -s localhost:8080/greeting # sysprop
APP_GREETING=env java -Dapp.greeting=sysprop -jar target/shop.jar --app.greeting=cli
curl -s localhost:8080/greeting # clifile-in-jar
env
sysprop
cliEach added source beats the one before. The lesson of the table made concrete: the file in the jar is the weakest, and the environment already overrides it, with no code change. A surprise like hola almost always means one of the higher sources is set where you did not look: a Kubernetes env entry, a leftover JAVA_TOOL_OPTIONS carrying -Dapp.greeting, or a SPRING_APPLICATION_JSON in a deployment manifest. How JAVA_TOOL_OPTIONS reaches the JVM is covered in setting JVM options in Docker.
Environment variable names
An environment variable cannot contain dots or dashes in most shells, so Boot maps names by a rule: upper case, dots and dashes replaced as follows.
| Property | Variable |
|---|---|
app.greeting | APP_GREETING |
app.max-retries | APP_MAXRETRIES |
spring.datasource.url | SPRING_DATASOURCE_URL |
app.regions[0] | APP_REGIONS_0 |
A dash is removed rather than turned into an underscore, so APP_MAX_RETRIES is a different property (app.max.retries) and does nothing for app.max-retries. Confusing the two is the most common reason an override "has no effect". The full naming rules, including lists and maps, are in importing config from environment variables. A missing value for a placeholder fails at startup with the message in Could not resolve placeholder.
Profiles
A profile selects extra files. With spring.profiles.active=prod, Boot loads application-prod.yaml after application.yaml and gives it higher priority, so keys in the profile file win:
app:
greeting: from-prod-profilejava -jar target/shop.jar --spring.profiles.active=prod
curl -s localhost:8080/greetingfrom-prod-profileWithin one file, you can also use multi-document YAML with spring.config.activate.on-profile to keep a few profile overrides together. Profiles combine: --spring.profiles.active=prod,eu loads both files, and for a key defined in both, the later profile in the list wins. Which file layout to choose is discussed in properties versus YAML, and where these files belong in a project in the Spring Boot project structure.
An important property of profiles: a profile-specific file beats the default file at the same location, but a plain environment variable still beats a profile-specific file inside the jar. Env and system properties are above every file.
External config files
Boot also looks outside the jar, which is how operations change settings without a rebuild. The search locations, in increasing priority, are the classpath root, the classpath /config package, the current directory, the ./config/ subdirectory of the current directory and its immediate subdirectories. A file named application.yaml placed next to the jar overrides the one inside it:
ls
# shop.jar application.yaml
cat application.yaml
# app:
# greeting: from-sibling-file
java -jar shop.jarYou can add or replace locations explicitly:
java -jar shop.jar --spring.config.additional-location=file:/etc/shop/
java -jar shop.jar --spring.config.import=optional:file:/etc/shop/secrets.yamladditional-location adds files that win over the defaults, while spring.config.location replaces the defaults entirely, which is rarely what you want because you lose the jar's own file. The optional: prefix prevents a startup failure when the file is absent. For containers, the manifest side of mounting such a file is in writing Kubernetes manifests for a Java service.
See the winner
Do not reason about it; ask the running application. The env actuator endpoint reports the value of a property and which source supplied it, with a list of every source that defined it:
management:
endpoints:
web:
exposure:
include: envcurl -s localhost:8080/actuator/env/app.greeting | jq{
"property": { "source": "systemProperties", "value": "sysprop" },
"activeProfiles": [],
"propertySources": [
{ "name": "commandLineArgs" },
{ "name": "systemProperties", "property": { "value": "sysprop" } },
{ "name": "systemEnvironment", "property": { "value": "env", "origin": "System Environment Property \"APP_GREETING\"" } },
{ "name": "Config resource 'class path resource [application.yaml]' via location 'optional:classpath:/'", "property": { "value": "file-in-jar", "origin": "class path resource [application.yaml] - 2:13" } }
]
}The top property.source is the winner, and propertySources lists every source in priority order with the value it holds and, for files, the line number. This one request answers the question. The endpoint is described in the actuator env API reference. Never expose it publicly: it shows configuration, and while values of keys like password are masked, the masking is by name and not reliable. Keep it on an internal management port with authentication, or enable it only while debugging.
Common surprises
- A value set in both the file and a profile file. The profile wins. Check whether the profile you did not mean is active (
curl /actuator/env | jq .activeProfiles). - A property that never changes in a test. A test slice may load a different set of files;
@SpringBootTest(properties = "...")and@TestPropertySourceare higher than anything in the application. - A relaxed-binding clash.
app.maxRetries,app.max-retriesandapp.max_retriesare the same property under binding, so two sources using different spellings both count and the higher priority one wins. - Lists replace, not merge. Defining
app.regionsin two sources does not combine them; the winning source's entire list is used. Maps, by contrast, merge key by key. - A command-line argument without the dashes.
app.greeting=cliis treated as a program argument, not a property. It must be--app.greeting=cli.
Where this does not apply
This order is for Spring Boot's Environment. A library that reads System.getenv or its own file directly ignores it. A Spring Cloud Config Server or Vault source slots into the list by its own priority and can override the jar and external files, so check its settings when a value comes from nowhere you can find. And Quarkus uses a different ordering and profile syntax, covered in Quarkus configuration profiles, so do not carry these rules across frameworks.


