Common Spring Boot application.yml Mistakes

Mistake 1: indentation moves a setting to the wrong level

YAML uses indentation to express hierarchy. A setting may look only two spaces away from the right place, but its meaning can be completely different. Spring Boot may not fail at startup because the YAML document is still valid; the value is simply bound to the wrong location.

A common symptom is that server.port, spring.datasource, or management.endpoints is present in the file but the application still uses defaults. In that case, check parent-child alignment before blaming the plugin or Spring Boot version.

spring:
  datasource:
  url: jdbc:postgresql://localhost:5432/app
  username: app

# correct
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/app
    username: app

Mistake 2: a profile file overrides the base setting

Values in application.yml can be overridden by application-dev.yml, application-test.yml, or application-prod.yml. Many settings are not missing; they are replaced later by the active profile.

When debugging, confirm spring.profiles.active first, then search for the same key across environment files. In team projects, avoid committing local debug ports, test database URLs, or temporary log levels into shared profiles.

• Check startup arguments, environment variables, and active profile settings
• Search whether the same key appears in multiple application-*.yml files
• Keep one authoritative value for each environment
• Use startup logs or Actuator env data to confirm the final value

Mistake 3: value type does not match the target property

YAML has its own parsing rules for numbers, booleans, strings, and lists. Quotes are not always wrong, but when a value is bound to a strongly typed property, the wrong type can cause binding errors or unexpected behavior.

Use consistent styles for ports, durations, booleans, and lists. If unsure, start a minimal project and inspect binding errors or the final runtime value.

server:
  port: 8080
spring:
  main:
    lazy-initialization: false
management:
  endpoints:
    web:
      exposure:
        include:
          - health
          - info

Mistake 4: checking only one configuration source

The final Spring Boot environment does not come from application.yml alone. Command-line arguments, environment variables, external files, and profile-specific files can all override values. If the file contains server.port: 8080 but the process starts with --server.port=9090, the runtime port should be 9090.

Inspect the actual launch command and active profiles before searching for the same key. Do not expose Actuator env or configprops publicly just for troubleshooting. In a local environment, combine startup logs, the IDE Run Configuration, and focused configuration-binding tests to confirm the final value.

# application.yml
server:
  port: 8080

# higher-priority command-line argument
java -jar app.jar --server.port=9090

Minimal reproduction and primary references

A minimal reproduction keeps one configuration file and one key under test. Run without profiles, environment variables, or extra launch arguments first. Once the base value works, restore external sources one at a time. This separates YAML structure errors from property precedence problems.

Spring Boot's externalized configuration reference maintains the PropertySource order and documents limits such as environment-variable binding for indexed YAML lists. Check the reference for the Spring Boot line you actually run whenever precedence or complex collections are involved.

• Spring Boot: Externalized Configuration
• Spring Boot: Profiles

Related guides

• Troubleshooting YAML Indentation Issues
• Complete Guide to Spring Boot Profiles