Javaspringbootoverridingenvironment Variables Guide Medium

Last Updated: Spring Boot: How to Specify Environment Variables with Dashes in application.properties (And Why Yours Isn't Overriding) Spring Boot has revolutionized how developers configure applications, offering flexible property management through files like application.properties , environment variables, command-line arguments, and more. A common scenario is overriding properties defined in application.properties with environment variablesâespecially in containerized or cloud environments. However, confusion often arises when properties in application.properties contain dashes (e.g., app.my-service-url ), and the corresponding environment variable fails to override the value. Why does this happen?

And how do you correctly map environment variables to dashed properties? This blog dives into Spring Bootâs configuration binding rules, demystifies the dash-to-environment-variable conversion, and troubleshoots common override failures. Table of Contents# - Understanding Spring Boot Configuration Binding - The Dash Problem: Environment Variables vs. application.properties - How Spring Boot Resolves Environment Variables with Dashes - Why Your Environment Variable Isnât Overriding: Common Pitfalls - Step-by-Step Example: Making It Work - Advanced Scenarios - Conclusion - References 1.

Understanding Spring Boot Configuration Binding# Spring Boot uses a process called "relaxed binding" to map external configuration sources (e.g., environment variables, system properties) to application properties. This feature allows flexibility in how properties are named across different sources. Key points: - Property Sources: Spring Boot loads properties from multiple sources in a specific order (highest precedence first): - Command-line arguments - Environment variables application-{profile}.properties (active profile)application.properties (default)@PropertySource annotations (if defined) - Relaxed Binding Rules: Property names are case-insensitive, and separators like dots ( .

), underscores (_ ), and dashes (- ) are treated interchangeably in many cases. For example,app.myProp ,app.my-prop , andapp.my_prop are considered equivalent inapplication.properties . 2. The Dash Problem: Environment Variables vs. application.properties # In application.properties , dashes (- ) are widely used to improve readability (e.g., app.api-endpoint , database.connection-timeout ). However, environment variables in operating systems (Linux, macOS, Windows) have strict naming rules: - They cannot contain dashes (most shells interpret - as an option flag). - They are typically uppercase (convention, though Linux/macOS are case-sensitive).

They use underscores ( _ ) as separators instead of dots or dashes. This mismatchâdashes in application.properties vs. underscores/uppercase in environment variablesâoften leads to confusion. For example, if you define app.my-service-url=default in application.properties , what environment variable should you set to override it? 3. How Spring Boot Resolves Environment Variables with Dashes# Spring Boot bridges the gap between dashed properties and environment variables using a name conversion process.

When looking for an environment variable to override a property, it converts the property name to an environment variable name using these rules: Conversion Steps:# - Replace dots ( . ) and dashes (- ) with underscores (_ ). - Convert camelCase to UPPER_SNAKE_CASE (e.g., myProp âMY_PROP ). - Uppercase the entire result. Example Conversions:# Why this works: Spring Boot treats dashes and dots as separators, and environment variables use underscores to replace these separators. The uppercase convention ensures compatibility across OSes. 4.

Why Your Environment Variable Isnât Overriding: Common Pitfalls# Even with the conversion rules, environment variables often fail to override properties. Here are the most likely causes: Pitfall 1: Incorrect Environment Variable Name# The #1 issue is using the wrong environment variable name. For example: - Using APP.MY-PROP (dots/dashes instead of underscores). - Using app_my_service_url (lowercase instead of uppercase). - Forgetting to replace dashes with underscores (e.g., APP_MY-SERVICE_URL ). Fix: Use the converted name from the table above (e.g., APP_MY_PROP for app.my-prop ).

Pitfall 2: Typos in Property/Environment Variable Names# A simple typo (e.g., APP_MY_PROP vs. APP_MY_PROP_TYPO ) will cause Spring Boot to ignore the environment variable. Fix: Double-check spelling and case. Use tools like printenv (Linux/macOS) or echo %VAR_NAME% (Windows) to verify the environment variable is set. Pitfall 3: Misunderstanding Profile-Specific Properties# If your property is defined in a profile-specific file (e.g., application-dev.properties ), you must ensure the active profile matches. Environment variables override properties regardless of the profile, but the property must exist in the active configuration.

Example: If app.my-prop is only in application-dev.properties , set SPRING_PROFILES_ACTIVE=dev to activate the profile before overriding with APP_MY_PROP . Pitfall 4: Outdated Spring Boot Version# Older Spring Boot versions (pre-2.0) had stricter binding rules. For example, camelCase properties required exact environment variable matches (e.g., app.apiKey needed APP_APIKEY instead of APP_API_KEY ). Fix: Use Spring Boot 2.0+ for relaxed binding of camelCase/dashes to underscores. Pitfall 5: Property Source Precedence# While environment variables have high precedence, command-line arguments or SPRING_APPLICATION_JSON can override them.

For example, java -jar app.jar --app.my-prop=cli-override will take precedence over APP_MY_PROP . Fix: Check if another high-precedence source (command line, SPRING_APPLICATION_JSON ) is overriding your environment variable. 4. Why Your Environment Variable Isnât Overriding: Common Pitfalls# Even with the conversion rules, environment variables often fail to override properties. Here are the most likely causes: Pitfall 1: Incorrect Environment Variable Name# The #1 issue is using the wrong environment variable name. For example: - Using APP.MY-PROP (dots/dashes instead of underscores). - Using app_my_service_url (lowercase instead of uppercase).

Forgetting to replace dashes with underscores (e.g., APP_MY-SERVICE_URL ). Fix: Use the converted name from the table above (e.g., APP_MY_PROP for app.my-prop ). Pitfall 2: Typos in Property/Environment Variable Names# A simple typo (e.g., APP_MY_PROP vs. APP_MY_PROP_TYPO ) will cause Spring Boot to ignore the environment variable. Fix: Double-check spelling and case. Use tools like printenv (Linux/macOS) or echo %VAR_NAME% (Windows) to verify the environment variable is set.

Pitfall 3: Misunderstanding Profile-Specific Properties# If your property is defined in a profile-specific file (e.g., application-dev.properties ), you must ensure the active profile matches. Environment variables override properties regardless of the profile, but the property must exist in the active configuration. Example: If app.my-prop is only in application-dev.properties , set SPRING_PROFILES_ACTIVE=dev to activate the profile before overriding with APP_MY_PROP . Pitfall 4: Outdated Spring Boot Version# Older Spring Boot versions (pre-2.0) had stricter binding rules.

For example, camelCase properties required exact environment variable matches (e.g., app.apiKey needed APP_APIKEY instead of APP_API_KEY ). Fix: Use Spring Boot 2.0+ for relaxed binding of camelCase/dashes to underscores. Pitfall 5: Property Source Precedence# While environment variables have high precedence, command-line arguments or SPRING_APPLICATION_JSON can override them. For example, java -jar app.jar --app.my-prop=cli-override will take precedence over APP_MY_PROP . Fix: Check if another high-precedence source (command line, SPRING_APPLICATION_JSON ) is overriding your environment variable. 5.

Step-by-Step Example: Making It Work# Letâs walk through a concrete example to override a dashed property with an environment variable. Step 1: Create a Spring Boot Project# Generate a basic Spring Boot app (using Spring Initializr) with the "Configuration Processor" dependency (for @ConfigurationProperties ).

Step 2: Define a Dashed Property# In src/main/resources/application.properties , add: Step 3: Bind Properties to a Configuration Class# Create a @ConfigurationProperties class to bind these properties: Step 4: Expose Properties via a REST Endpoint# Create a controller to display the properties: Step 5: Run Without Environment Variables# Start the app and visit http://localhost:8080/config .

The response will show the default values: Step 6: Override with Environment Variables# Set environment variables to override the dashed property and timeout : Linux/macOS:# Windows (Command Prompt):# Windows (PowerShell):# Step 7: Verify the Override# Visit http://localhost:8080/config again. The environment variables now override the properties: Success! The environment variables APP_MY_SERVICE_URL and APP_TIMEOUT overrode app.my-service-url and app.timeout . 6.

Advanced Scenarios# Nested Properties# For nested properties (e.g., app.database.url , app.database.username ), the environment variable uses underscores for each level: - Property: app.database.connection-pool-size=10 - Environment variable: APP_DATABASE_CONNECTION_POOL_SIZE=20 CamelCase Properties# For camelCase properties (e.g., app.apiKey ), Spring Boot converts them to uppercase with underscores: - Property: app.apiKey=default-key - Environment variable: APP_API_KEY=overridden-key Using @Value Instead of @ConfigurationProperties # If you use @Value("${app.my-service-url}") directly in a component, the same environment variable rules apply: Docker Environment Variables# In Docker, set environment variables in docker run or docker-compose.yml : 7.

Conclusion# Overriding dashed properties in application.properties with environment variables is straightforward once you understand Spring Bootâs name conversion rules. Remember: - Convert dashes/dots to underscores and uppercase the environment variable name (e.g., app.my-service-url âAPP_MY_SERVICE_URL ). - Avoid common pitfalls like typos, incorrect case, or outdated Spring Boot versions. - Use @ConfigurationProperties or@Value to bind properties, and verify overrides with Actuatorâs/env endpoint or debug logs. With these steps, youâll confidently manage configuration across environmentsâwhether in development, testing, or production.

People Also Asked

• Java Spring Boot Overriding Environment Variables Guide
• Spring Boot: How to Specify Environment Variables with Dashes in ...
• Using Environment Variables in Spring Boot's Properties Files
• Using Environment Variables in Spring Boot - danvega.dev
• Environment Variables in Spring Boot Properties: Override default ...
• 4 Ways to Configure Environment Variables in Spring Boot