Introduction

Spring Boot already supports profile-specific configuration through files such as application-dev.yml, but some projects also need custom property files for specific modules or environments. The clean approach is to use Spring Boot's config data system so the right files load declaratively and predictably.

Start with Built-In Profile Files

Before adding custom imports, use the standard profile mechanism where possible.

1# application.yml
2app:
3  featureX: false
4  timeoutMs: 1500

1# application-dev.yml
2app:
3  featureX: true
4  timeoutMs: 5000

Activate the profile at runtime:

java -jar app.jar --spring.profiles.active=dev

This is the simplest and best-documented configuration path, so it should be your default starting point.

Import Extra Files with spring.config.import

When you need more files than the built-in naming convention provides, use spring.config.import.

1# application.yml
2spring:
3  config:
4    import:
5      - optional:classpath:common-settings.yml
6      - optional:classpath:integration/payment.yml

You can also place imports inside a profile-specific file.

1# application-prod.yml
2spring:
3  config:
4    import:
5      - optional:classpath:prod-secrets.yml

The optional: prefix prevents startup failure when a file is intentionally absent in some environments.

Scope Custom Files to Specific Profiles

If a custom file should be loaded only for one profile, express that declaratively in profile files or activation blocks instead of scattering Environment checks through Java code.

1# application.yml
2spring:
3  config:
4    activate:
5      on-profile: dev
6    import: "optional:classpath:dev-overrides.yml"

This keeps the configuration story visible in one place and makes precedence easier to reason about.

Bind Values to Typed Classes

Custom property files are easier to use safely when they are bound into typed configuration objects.

1package com.example.config;
2
3import org.springframework.boot.context.properties.ConfigurationProperties;
4
5@ConfigurationProperties(prefix = "billing")
6public class BillingProperties {
7    private String provider;
8    private int timeoutMs;
9
10    public String getProvider() {
11        return provider;
12    }
13
14    public void setProvider(String provider) {
15        this.provider = provider;
16    }
17
18    public int getTimeoutMs() {
19        return timeoutMs;
20    }
21
22    public void setTimeoutMs(int timeoutMs) {
23        this.timeoutMs = timeoutMs;
24    }
25}

Then enable configuration property scanning:

1import org.springframework.boot.SpringApplication;
2import org.springframework.boot.autoconfigure.SpringBootApplication;
3import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
4
5@SpringBootApplication
6@ConfigurationPropertiesScan
7public class Application {
8    public static void main(String[] args) {
9        SpringApplication.run(Application.class, args);
10    }
11}

Typed binding is safer than scattering raw string lookups across the codebase.

Use @PropertySource Only for Narrow Legacy Cases

@PropertySource can still load .properties files, but it is usually a poor fit for modern profile-layered YAML configuration.

1import org.springframework.context.annotation.Configuration;
2import org.springframework.context.annotation.PropertySource;
3
4@Configuration
5@PropertySource("classpath:legacy.properties")
6public class LegacyConfig {
7}

For most current Spring Boot applications, config-data imports are easier to understand and handle precedence more cleanly.

Debug Precedence and Missing Values

If the loaded values are not what you expect, increase config logging to see which sources were considered.

logging.level.org.springframework.boot.context.config=DEBUG

In non-production environments, actuator endpoints such as env and configprops can also help explain which property source won.

Common Pitfalls

One common problem is mixing older bootstrap-era patterns with modern config-data imports and then misreading property precedence.

Another is using @PropertySource for YAML-based profile setups and expecting it to behave like the config-data system. It does not provide the same profile-aware layering model.

Teams also create too many overlapping files with the same keys and no clear ownership. If every file can override every property, debugging quickly becomes difficult.

Summary

• Use built-in profile files first, because they are the simplest Spring Boot mechanism.
• Use spring.config.import when you need additional custom property files.
• Keep profile activation declarative instead of checking profiles manually in code.
• Bind settings into typed configuration classes for safer access.
• Use debug logging and actuator tools when you need to inspect precedence and property sources.