Spring Boot Configuration Priority Order

If you have ever stared at your Spring Boot application wondering “Why is it picking the wrong port?” or “Where is this database URL coming from?” You are not alone. One of the most common sources of confusion among Java developers is how Spring Boot decides which configuration value to use when the same property is defined in multiple places.

This guide breaks down the externalized configuration property priority into a simple, visual hierarchy that you can bookmark for your next project or technical interview.

What Is Externalized Configuration in Spring Boot?

As per Spring Boot official documentation on externalized configuration, Externalized configuration means keeping your application settings outside your compiled code so you can change behavior without rebuilding the JAR. Spring Boot supports multiple sources: application.properties, environment variables, command-line arguments, and more, and merges them at runtime.

The catch? When the same key exists in two sources, Spring Boot does not throw an error. It silently picks the winner based on a fixed priority order. Understanding that order saves hours of debugging.

Spring Boot Configuration Priority Order

The 4-Level Priority Hierarchy (Highest → Lowest)

The diagram below shows the simplified but practically critical priority stack every developer should memorize:

1. Command-Line Arguments (Highest Priority)

Values passed directly when launching the JVM take absolute precedence.

java -jar app.jar --spring.profiles.active=dev --server.port=8080

Use this for one-off overrides during local testing or emergency production tweaks. Nothing beats command-line arguments.

2. Environment Variables

Variables set in the OS or container environment come next.

export SPRING_PROFILES_ACTIVE=dev

export SERVER_PORT=8080

Spring Boot applies relaxed binding automatically, so SERVER_PORT maps to server.port and SPRING_DATASOURCE_URL maps to spring.datasource.url. This is the go-to method for Docker, Kubernetes, and CI/CD pipelines because it keeps secrets out of source control.

3. Profile-Specific Files

Files like application-dev.properties, application-dev.yml, or application-prod.properties load after environment variables but before the default config.

Activate a profile via:

• Command line: –spring.profiles.active=dev
• Environment variable: SPRING_PROFILES_ACTIVE=dev
• Or inside application.properties: spring.profiles.active=dev

These files are perfect for environment-specific defaults: development URLs, staging credentials, or production logging levels.

4. application.properties / application.yml (Lowest Priority)

The baseline configuration files inside your src/main/resources directory sit at the bottom of the stack.

Think of these as sensible defaults for local development. Any of the three sources above can override them without touching a single line of code.

Real-World Example: Which Value Wins?

Imagine server.port is defined in four places:

Final result: 8083 because command-line arguments hold the highest priority.

Quick Memory Trick for Interviews

Use this mnemonic to ace Spring Boot interview questions:

CLI > ENV > PROFILE > DEFAULT

Command Line beats Environment, Environment beats Profile, Profile beats Default.

Interviewers love asking: “If I set a property in application.properties and also pass it as an environment variable, which one wins?” Now you know: the environment variable wins.

Best Practices for Production

• Never commit secrets to application.properties. Use environment variables or secret managers.
• Use profile-specific files (application-prod.yml) for environment-specific non-secret defaults.
• Reserve command-line arguments for temporary debugging, not permanent deployment configs.
• Avoid mixing .properties and .yml for the same profile in the same project. If both exist, .properties takes precedence over .yml.
• Log active profiles at startup with debug=true or –debug to verify which files are loading.

Common Mistakes to Avoid

Conclusion

Spring Boot’s externalized configuration system is powerful once you understand the priority ladder. The golden rule is simple: higher-priority sources always override lower-priority ones. Master this hierarchy and you will debug faster, deploy safer, and impress interviewers with confidence.

For other Java related topics, kindly go through:

Microservices Tutorial,  Spring Boot Tutorial,  Core Java,  System Design Tutorial,  Java MCQs/Quizzes, Java Design Patterns etc.