Spring Boot Configuration: When to Require, Default, or Leave Empty Environment Variables

Spring Boot supports flexible environment variable interpolation in your application.yml files, but it's important to know when to require a variable, leave it empty, or provide a default value.

Choosing the right approach improves reliability, avoids silent misconfigurations, and makes your application easier to maintain across environments.

Let’s break it down into three types:

🔒 1. ${VARIABLE} — Required

This format means the variable must be defined.

If it's not present, Spring Boot will fail to start with an error.

✅ When to use:

Use this for critical configuration values your application can’t run without:

• Database connection details
• API credentials
• Encryption keys

spring: datasource: url: ${DB_URL} # Must be set username: ${DB_USER} # Must be set password: ${DB_PASS} # Must be set 

🟡 2. ${VARIABLE:} — Optional (empty by default)

This syntax allows the variable to be undefined, in which case it defaults to an empty string.

✅ When to use:

Use when the value is not always required, and you will handle its presence at runtime.

external: api-key: ${EXTERNAL_API_KEY:} # Will be empty if not defined 

📌 Remember to check if it's empty before using it in your code.

🟢 3. ${VARIABLE:default} — Optional with fallback value

This format sets a default value if the variable is not defined.

✅ When to use:

Use when a sensible default exists and makes development easier. This avoids overconfiguring every environment unnecessarily.

server: port: ${SERVER_PORT:8080} # Uses port 8080 if not set 

✅ Best Practices Summary

📄 Example: application.yml with Best Practices

spring: profiles: active: ${SPRING_PROFILES_ACTIVE:dev} # Default to 'dev' datasource: url: ${DB_URL} # ❗ Required username: ${DB_USERNAME} # ❗ Required password: ${DB_PASSWORD} # ❗ Required driver-class-name: ${DB_DRIVER:com.mysql.cj.jdbc.Driver} # ✅ Default fallback jpa: hibernate: ddl-auto: ${HIBERNATE_DDL:auto} # ✅ Default server: port: ${SERVER_PORT:8080} # ✅ Default port servlet: context-path: ${CONTEXT_PATH:/} client: id: ${CLIENT_ID:localhost} # ✅ Fallback value for local use api-key: ${EXTERNAL_API_KEY:} # 🔸 Optional management: endpoint: env: show-values: WHEN_AUTHORIZED # Safer than ALWAYS endpoints: web: base-path: /actuator exposure: include: health,info security: jwt: secret: ${JWT_SECRET} # ❗ Required expiration: ${JWT_EXPIRATION:3600} # ✅ Default in seconds app: environment: ${APP_ENVIRONMENT:local} feature-flag: enable-beta: ${ENABLE_BETA_FEATURE:false} 

🛡️ Final Advice

Always document which environment variables are mandatory and validate them early when possible. This avoids surprises during deployment and improves your system’s robustness.