Understanding SpringBoot External Configuration Loading Priority

SpringBoot supports dozens of external configuration sources, but developers often get confused about the loading order, override rules, environment-specific priorities, command‑line overrides, and Docker environment variable precedence, leading to frequent runtime issues such as unexpected port changes.

Core Rules

Higher priority configurations are loaded later; later‑loaded values overwrite earlier ones.

Priority order (high to low): runtime arguments > OS environment variables > external configuration files > internal configuration files > class‑path defaults > hard‑coded defaults.

Two Configuration Systems

Native SpringBoot : application‑*.yml/properties, command‑line args, environment variables, no spring‑cloud‑context dependency.

Spring Cloud Extension : bootstrap.yml/bootstrap.properties (effective only with spring‑cloud‑context), highest priority among all application configurations.

Complete Priority List

Command‑line arguments (e.g., --server.port=8090) – globally highest, cannot be overridden.

JVM system properties (e.g., -Dserver.port=8081) – second only to command‑line.

OS environment variables (e.g., SERVER_PORT=9000) – map to kebab‑case keys.

JNDI attributes (e.g., java:comp/env) – used mainly with external Tomcat.

Servlet context init params (web.xml <context-param>) – for legacy containers.

Servlet init params – also legacy.

External config files in ./config/ folder – higher than root‑level files.

External config files in the application’s root directory.

Classpath /config/ resources (inside BOOT-INF/classes/config) – higher than root classpath.

Classpath root resources (e.g., resources/application.yml).

Profile‑specific files on the classpath (e.g., application-dev.yml) – override base files; later‑activated profiles override earlier ones.

Profile‑specific files in external ./config/ – higher than classpath profiles.

Profile‑specific files in the external root directory.

Random value placeholders ( ${random.int}, ${random.uuid}, etc.) – only used when no fixed key exists. @PropertySource imported files – lower than all native application sources.

Bootstrap files ( bootstrap.yml, bootstrap‑{profile}.yml) – loaded at the earliest stage and have the lowest overall priority; they are ignored in pure SpringBoot 3 projects without Spring Cloud.

Hard‑coded defaults in code (e.g., @ConfigurationProperties default values, @Value("${key:default}")) – used only when no external source provides the key.

Same‑Directory Loading Rules

When files exist in the same directory, the order from highest to lowest is:

./config/application-dev.yml

./config/application.yml

./application-dev.yml

./application.yml

YML vs. Properties

Within the same priority level, .properties files override .yml files for identical keys.

SpringBoot 2.x vs 3.x Differences

Bootstrap mechanism is removed in pure SpringBoot 3; only retained when Spring Cloud 2023+ is added.

Environment‑variable binding in 3.x is case‑sensitive and drops some loose matching rules.

Underlying PropertySource sorting logic remains unchanged. @ConfigurationProperties is recommended over scattered @Value usage.

3.x validates unknown configuration fields more strictly, helping catch typos.

Practical Example: Port Configuration

Five locations set server.port:

Inside JAR: application.yml – server.port=8080 External ./config/application.yml – server.port=8081 OS env var SERVER_PORT=8082 JVM arg -Dserver.port=8083 Command‑line arg --server.port=8084 Final effective port is 8084 because command‑line arguments have the highest priority.

SpringCloud Bootstrap Override Demo

spring:
  datasource:
    url: bootstrap-mysql

Application application.yml defines url: local-mysql. Adding the command‑line argument --spring.datasource.url=prod-mysql results in the final value prod-mysql because bootstrap loads first, then application overrides it, and the command‑line argument overrides everything.

Production Configuration Layering Best Practices

Low layer (inside JAR) : generic business defaults (thread pools, log format, feature flags) – no secrets.

Middle layer (external config/ ) : environment‑specific addresses for databases and middleware.

High layer (container env vars / startup args) : sensitive production data (DB credentials, API keys, ports) – never stored in files.

SpringCloud microservices : bootstrap only holds configuration‑center addresses; all business configs are fetched from the center and can be overridden by env vars.

Configuration Conflict Diagnosis

Run with --debug to print the full PropertySource order and values.

Enable SpringBoot Actuator /env endpoint to view each source and the final resolved value.

Inject Environment and iterate MutablePropertySources to log source names; the printed order reflects descending priority.

Understanding this loading hierarchy resolves the majority of online configuration conflicts, missing parameters, and environment‑switching issues, and is essential for building robust starters, multi‑environment deployments, and containerized K8s services.