Configuration precedence order in Spring Boot - Deep Dive

Overview - Configuration precedence order

What is it?

Configuration precedence order in Spring Boot is the rule that decides which configuration setting wins when the same property is defined in multiple places. Spring Boot allows you to set properties in many ways, like files, environment variables, command-line arguments, or code. The precedence order tells Spring Boot which source to trust first when it finds conflicts. This helps your app behave predictably and makes it easy to customize settings for different environments.

Why it matters

Without a clear precedence order, your app could behave unpredictably because it wouldn't know which configuration to use. Imagine changing a setting in one place but seeing no effect because another source overrides it silently. Knowing the order helps you control your app’s behavior, avoid bugs, and manage settings cleanly across development, testing, and production.

Where it fits

Before learning configuration precedence, you should understand basic Spring Boot configuration concepts like application.properties and YAML files. After this, you can learn about profiles, externalized configuration, and how to customize configuration sources for advanced setups.

Mental Model

Core Idea

Spring Boot checks configuration sources in a fixed order and uses the first value it finds for each property.

Think of it like...

It's like choosing clothes from different drawers: you always pick from the top drawer first, and only if the item isn't there, you check the next drawer below.

┌───────────────────────────────┐
│ Configuration Sources (Order) │
├───────────────────────────────┤
│ 1. Command-line arguments      │
│ 2. Java System properties      │
│ 3. OS Environment variables    │
│ 4. Application properties file │
│ 5. Default properties          │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

What is Spring Boot Configuration

Concept: Introduce the idea of configuration in Spring Boot and why it matters.

Spring Boot apps use configuration properties to control behavior like server ports, database URLs, or feature toggles. These properties can be set in files like application.properties or application.yml, or passed in other ways. Configuration lets you change app behavior without changing code.

Result

You understand that configuration is how you tell your app what to do without rewriting it.

Understanding configuration is the first step to controlling your app’s behavior flexibly.

2

Foundation

Multiple Configuration Sources Exist

Concept: Explain that Spring Boot supports many ways to provide configuration values.

You can set properties in several places: command-line arguments, environment variables, Java system properties, config files inside your app, or default values in code. Each source can provide the same property with different values.

Result

You realize configuration is not just one file but many possible places.

Knowing multiple sources exist prepares you to understand why precedence is needed.

3

Intermediate

Why Precedence Order is Needed

🤔Before reading on: do you think Spring Boot uses the last or the first property it finds when duplicates exist? Commit to your answer.

Concept: Introduce the problem of conflicting property values and the need for a clear rule to pick one.

When the same property is set in multiple places, Spring Boot must decide which value to use. Without a rule, the app could behave unpredictably. Precedence order is the rule that says which source wins when conflicts happen.

Result

You understand that precedence order prevents confusion and bugs.

Knowing that Spring Boot uses a fixed order helps you predict which setting will apply.

4

Intermediate

Standard Precedence Order in Spring Boot

🤔Before reading on: do you think command-line arguments have higher or lower priority than environment variables? Commit to your answer.

Concept: Teach the exact order Spring Boot uses to check configuration sources.

Spring Boot checks sources in this order: 1) Command-line arguments, 2) Java system properties (like -D flags), 3) OS environment variables, 4) application.properties or application.yml files inside your app, 5) default values coded in your app. The first source that has the property wins.

Result

You can now predict which configuration value will be used based on where you set it.

Understanding this order lets you override settings easily by choosing the right source.

5

Intermediate

Profiles and Their Effect on Precedence

🤔Before reading on: do you think profile-specific files override the main application.properties or the other way around? Commit to your answer.

Concept: Explain how Spring Boot profiles add another layer to configuration precedence.

Spring Boot supports profiles like 'dev' or 'prod' to separate settings. Profile-specific files (like application-dev.properties) override the main application.properties for active profiles. These profile files are checked after environment variables but before default properties.

Result

You understand how to customize configuration per environment using profiles.

Knowing profile precedence helps you manage environment-specific settings cleanly.

6

Advanced

External Config and Its Priority

🤔Before reading on: do you think external config files have higher or lower priority than packaged application.properties? Commit to your answer.

Concept: Teach how external config files outside the jar affect precedence.

Spring Boot allows placing config files outside the packaged app, like in /config folder or specified locations. These external files have higher priority than the packaged application.properties inside the jar, but lower than command-line args and Java system properties and environment variables.

Result

You can now use external config files to override packaged defaults without rebuilding the app.

Understanding external config priority enables flexible deployment and configuration management.

7

Expert

Customizing and Extending Precedence Order

🤔Before reading on: do you think Spring Boot lets you add your own config sources with custom priority? Commit to your answer.

Concept: Explain how advanced users can add or change configuration sources and their order.

Spring Boot’s Environment abstraction lets you add custom PropertySources programmatically. You can insert them at any position in the precedence order. This is useful for integrating config servers, encrypted properties, or dynamic sources. However, managing order carefully is crucial to avoid unexpected overrides.

Result

You know how to extend Spring Boot configuration beyond defaults for complex needs.

Knowing how to customize precedence unlocks powerful configuration strategies for large or secure apps.

Under the Hood

Spring Boot uses an Environment object that holds a list of PropertySources. When a property is requested, it searches these sources in order until it finds a value. Each PropertySource wraps a configuration source like a file or environment variables. This layered search ensures the first found value is used, implementing precedence.

Why designed this way?

This design allows flexible configuration from many sources without hardcoding priorities. It supports overriding defaults easily and adapts to different deployment environments. Alternatives like merging all sources without order would cause unpredictable behavior. The layered approach balances flexibility and predictability.

┌─────────────────────────────┐
│ Environment (PropertySources)│
├─────────────────────────────┤
│ 1. Command-line args         │
│ 2. Java System properties    │
│ 3. OS Environment variables  │
│ 4. External config files      │
│ 5. Packaged application files │
│ 6. Default properties         │
└─────────────────────────────┘
          ↓
  Property lookup stops at first match

Myth Busters - 4 Common Misconceptions

Quick: Do command-line arguments have lower priority than environment variables? Commit to yes or no.

Common Belief: Command-line arguments are less important than environment variables.

Reality: Command-line arguments have the highest priority and override environment variables.

Why it matters: If you think environment variables override command-line args, you might fail to override settings during app startup, causing confusion.

Quick: Does application.properties always override environment variables? Commit to yes or no.

Common Belief: Properties in application.properties always override environment variables.

Reality: Environment variables have higher priority than application.properties files.

Why it matters: Assuming the opposite can cause your environment variable changes to be ignored, leading to unexpected app behavior.

Quick: Can you add a new configuration source with higher priority than command-line args? Commit to yes or no.

Common Belief: You cannot add custom configuration sources with higher priority than command-line arguments.

Reality: You can add custom PropertySources programmatically and place them anywhere in the order, even above command-line args if needed.

Why it matters: Not knowing this limits advanced configuration strategies and integration with external config systems.

Quick: Do profile-specific properties have lower priority than the main application.properties? Commit to yes or no.

Common Belief: Profile-specific properties have lower priority than the main application.properties file.

Reality: Profile-specific properties override the main application.properties for active profiles.

Why it matters: Misunderstanding this can cause environment-specific settings to be ignored, breaking deployments.

Expert Zone

1

Some PropertySources like Config Data introduced in Spring Boot 2.4 have their own internal precedence that can affect overall order subtly.

2

Ordering of PropertySources can be influenced by the order of @PropertySource annotations and programmatic additions, which can cause unexpected overrides if not carefully managed.

3

Environment variables are relaxed binding aware, meaning they can map to properties with different naming conventions, which affects how precedence applies in practice.

When NOT to use

If you need dynamic configuration that changes at runtime, relying solely on static precedence order is insufficient. Instead, use Spring Cloud Config or refreshable PropertySources. Also, for very simple apps, complex precedence rules may be overkill; simple single-source config might be better.

Production Patterns

In production, command-line arguments or environment variables are commonly used to override packaged defaults for containerized apps. Profile-specific files manage environment differences. External config directories allow configuration without rebuilding. Custom PropertySources integrate secrets or config servers securely.

Connections

Dependency Injection

Builds-on

Understanding configuration precedence helps you see how dependency injection can receive different values depending on environment, making apps flexible.

Operating System Environment Variables

Same pattern

Both OS environment variables and Spring Boot config use layered overrides to manage settings, showing a common pattern in software configuration.

Version Control Branching

Analogy in different field

Just like configuration precedence chooses which setting wins, version control branching decides which code changes apply, illustrating conflict resolution in different domains.

Common Pitfalls

#1 Trying to override a property by changing application.properties but ignoring environment variables.

Wrong approach:

application.properties:
server.port=8080

Environment variable:
SERVER_PORT=9090

Expected port 8080 but app runs on 9090.

Correct approach:

Set the desired port in environment variable or command-line argument to override application.properties explicitly.

Root cause:

Misunderstanding that environment variables have higher priority than application.properties.

#2 Adding a custom PropertySource but placing it at the end, so it never overrides existing properties.

Wrong approach:

environment.getPropertySources().addLast(new CustomPropertySource());

Correct approach:

environment.getPropertySources().addFirst(new CustomPropertySource());

Root cause:

Not knowing that PropertySources are checked in order and that adding last means lowest priority.

#3 Expecting profile-specific properties to apply without activating the profile.

Wrong approach:

application-dev.properties contains overrides but app runs with default profile.

Correct approach:

Activate the profile with --spring.profiles.active=dev to apply profile-specific properties.

Root cause:

Not understanding that profile-specific files only apply when their profile is active.

Key Takeaways

Spring Boot uses a fixed order to decide which configuration value to use when duplicates exist.

Command-line arguments have the highest priority, followed by system properties, environment variables, external config files, and packaged files.

Profile-specific configuration files override main config files when their profile is active.

You can add custom configuration sources and control their priority programmatically.

Knowing configuration precedence prevents bugs and helps manage settings cleanly across environments.