Spring Boot Config Priority

Spring Boot loads configuration from multiple sources and applies overrides by priority. Higher-priority sources override lower ones. This article explains common sources, their order, and how to debug "config not taking effect" with a reference table.

Overview

• Sources: Command-line arguments, SPRING_APPLICATION_JSON, Servlet init params, system properties, application-{profile}.yml / .properties, application.yml / .properties, @PropertySource, and default values.
• Priority: Higher to lower. Command line overrides env vars, which override profile-specific files, which override the base application files.
• Profiles: Activated via spring.profiles.active (env, system property, or config). application-prod.yml is loaded when the prod profile is active and overrides application.yml.

Example

Example 1: Common priority (high to low)

Source	Description
Command line --key=value	Highest; overrides everything else
Environment variables	SPRING_APPLICATION_JSON, SERVER_PORT, etc.
System properties	-Dserver.port=9090
application-{profile}.yml	Loaded when profile is active
application.yml	Base config, lowest priority

Example 2: Override example

YAMLCopy
# application.yml
server:
  port: 8080

# application-prod.yml (when spring.profiles.active=prod)
server:
  port: 9090

# Command line --server.port=9091 overrides both

• Production config often lives in application-prod.yml or external config so it is not committed to the repo.

Example 3: Externalized config

• config/ directory next to the jar (or current working directory)
• application.yml next to the jar
• --config.location=file:/path/to/config/
• Lets you deploy the same jar with different config per environment without rebuilding.

Example 4: Full property source order (condensed)

1. Command-line arguments
2. SPRING_APPLICATION_JSON (env or system property)
3. ServletConfig init params
4. ServletContext init params
5. JNDI attributes
6. Java system properties (-D)
7. OS environment variables
8. application-{profile}.yml (for active profiles)
9. application.yml (or .properties)
10. @PropertySource on your @Configuration classes
11. Defaults (e.g. ServerProperties defaults)

Example 5: Relaxed binding

• server.port, server_port, and SERVER_PORT all map to server.port.
• Env vars typically use UPPER_SNAKE_CASE; config files use lowercase or kebab-case.
• Spring normalizes these to the canonical property name.

Example 6: Profile-specific overrides

YAMLCopy
# application.yml
logging:
  level:
    root: INFO

# application-dev.yml
logging:
  level:
    root: DEBUG
    org.springframework: TRACE

• When spring.profiles.active=dev, the dev overrides apply. Use profiles for dev, test, prod, etc.

Core Mechanism / Behavior

• PropertySources: Spring builds an ordered PropertySources list. The first occurrence of a property wins; higher-priority sources are checked first.
• Profile-specific files: application-{profile} is loaded only when that profile is active. Multiple profiles can be active; later profiles override earlier ones for the same property.
• Relaxed binding: Converts between formats so SERVER_PORT and server.port refer to the same property.
• Type conversion: Strings are converted to the target type (int, boolean, Duration, etc.) when bound to @ConfigurationProperties.

Debugging "Config Not Taking Effect"

• Check priority: Command line and env vars override files. If you set server.port in application.yml but also have SERVER_PORT in the env, the env wins.
• Check profile: Is the expected profile active? spring.profiles.active might be set by the runtime (e.g. cloud, K8s).
• Check property name: Typos and wrong nesting (e.g. server.port vs serverport) cause silent ignores. Use debug=true or actuator /actuator/configprops to inspect.
• Check type: Wrong type (e.g. string where number expected) can cause binding to fail or fall back to defaults.

Key Rules

• Sensitive data (passwords, keys): Use env vars or a secrets manager; do not put in application.yml committed to the repo.
• Use profiles for dev/test/prod; production should use profile-specific files or external config.
• Knowing the priority order helps debug "config not taking effect"; command line and env vars override file-based config.
• Prefer application.yml over application.properties for nested structure; both work.

What's Next

See Config Center for dynamic config and runtime overrides. See Spring Boot Startup for when config is loaded during startup.