Skip to content
javahacks.dev
Spring Boot

Spring Boot Configuration Precedence Order Explained

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

6 min read
Summarize in AI
Flat illustration of a start button surrounded by Spring Boot starters, with the Spring Boot, Docker, Spring Security and Spring logos.

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.

PrioritySourceExample
1Command-line arguments--app.greeting=cli
2SPRING_APPLICATION_JSON{"app":{"greeting":"json"}}
3Java system properties-Dapp.greeting=sysprop
4OS environment variablesAPP_GREETING=env
5Profile-specific files outside the jar./config/application-prod.yaml
6Profile-specific files inside the jarclasspath:application-prod.yaml
7Application files outside the jar./config/application.yaml
8Application files inside the jarclasspath:application.yaml
9@PropertySource on configuration classes@PropertySource("classpath:extra.properties")
10Default propertiesSpringApplication.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.

src/main/java/dev/javahacks/config/GreetingController.javajava
@RestController
class GreetingController {

    private final String greeting;

    GreetingController(@Value("${app.greeting:unset}") String greeting) {
        this.greeting = greeting;
    }

    @GetMapping("/greeting")
    String greeting() {
        return greeting;
    }
}
src/main/resources/application.yamlYAML
app:
  greeting: file-in-jar

Now run it five ways and read the answer each time:

Shell
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                      # cli
Text
file-in-jar
env
sysprop
cli

Each 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.

PropertyVariable
app.greetingAPP_GREETING
app.max-retriesAPP_MAXRETRIES
spring.datasource.urlSPRING_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:

src/main/resources/application-prod.yamlYAML
app:
  greeting: from-prod-profile
Shell
java -jar target/shop.jar --spring.profiles.active=prod
curl -s localhost:8080/greeting
Text
from-prod-profile

Within 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:

Shell
ls
# shop.jar  application.yaml
cat application.yaml
# app:
#   greeting: from-sibling-file
java -jar shop.jar

You can add or replace locations explicitly:

Shell
java -jar shop.jar --spring.config.additional-location=file:/etc/shop/
java -jar shop.jar --spring.config.import=optional:file:/etc/shop/secrets.yaml

additional-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:

src/main/resources/application.yamlYAML
management:
  endpoints:
    web:
      exposure:
        include: env
Shell
curl -s localhost:8080/actuator/env/app.greeting | jq
JSON
{
  "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 @TestPropertySource are higher than anything in the application.
  • A relaxed-binding clash. app.maxRetries, app.max-retries and app.max_retries are 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.regions in 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=cli is 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.

Also inDevOps
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.