Introduction

spring.profiles.include does not replace the active profile set. It adds extra profiles on top of the active ones, which means the real question is usually not "does it override" but "which property source wins when included and active profiles both define the same key?"

What spring.profiles.include Actually Does

In Spring Boot, spring.profiles.active selects profiles explicitly, while spring.profiles.include adds more profiles automatically.

spring.profiles.active=dev
spring.profiles.include=common,local

With that configuration, the application runs with dev, common, and local all active. The included profiles are additive. They are not a substitute for spring.profiles.active.

This is useful when one environment should always pull in a shared configuration such as common, regardless of which main profile is selected.

Precedence and Override Behavior

The confusing part is property precedence. If application-common.properties and application-dev.properties both define the same property, the active profile source usually wins over the included one in the final resolved value.

Example:

# application-common.properties
app.feature.enabled=false

# application-dev.properties
app.feature.enabled=true

# application.properties
spring.profiles.active=dev
spring.profiles.include=common

In practice, the application resolves app.feature.enabled to true because the explicitly active profile's property source takes precedence over the included profile's conflicting value.

So the best mental model is:

• 'include adds profiles'
• active profiles still have stronger override behavior when values conflict

A Small Example

Here is a minimal Spring Boot component that reads a resolved property:

1import org.springframework.beans.factory.annotation.Value;
2import org.springframework.boot.CommandLineRunner;
3import org.springframework.stereotype.Component;
4
5@Component
6public class DemoRunner implements CommandLineRunner {
7
8    @Value("${app.feature.enabled}")
9    private boolean featureEnabled;
10
11    @Override
12    public void run(String... args) {
13        System.out.println("app.feature.enabled = " + featureEnabled);
14    }
15}

With the files shown above, this prints true because the dev profile's value wins.

Where You Can Define It

A subtle but important rule in the Spring Boot reference docs is that spring.profiles.include must be defined in a non-profile-specific document. In other words, do not try to place it inside a profile-specific file that is itself activated by a profile.

That means this is fine:

# application.properties
spring.profiles.include=common

But using it inside a file that is already profile-scoped is the kind of setup that leads to surprising behavior and should be avoided.

When Profile Groups Are Better

If you find yourself repeatedly composing the same set of profiles, profile groups may be a cleaner option than long include chains.

spring.profiles.group.production[0]=proddb
spring.profiles.group.production[1]=prodmq

Now activating production also activates proddb and prodmq. This is often easier to reason about than scattering includes across several configuration files.

Another practical advantage is debugging. When profile composition is centralized, it is easier to explain why a property has a certain value and which profiles were meant to be active together. That becomes especially helpful in larger teams where configuration behavior has to be predictable across development, test, and production environments.

Common Pitfalls

One common mistake is assuming spring.profiles.include overrides the active profile list. It does not. It augments it.

Another is using include inside profile-specific documents. Spring Boot documentation explicitly warns against that pattern because profile activation must be determined before those documents are processed.

Developers also sometimes debug only the final property value and forget that several profiles may be active at once. When values conflict, precedence matters just as much as activation.

Finally, if profile composition is getting complicated, stop and consider profile groups or a simpler configuration strategy instead of adding more includes.

Summary

• 'spring.profiles.include adds profiles; it does not replace spring.profiles.active.'
• When properties conflict, explicitly active profiles typically win over included ones.
• Define spring.profiles.include only in non-profile-specific configuration documents.
• Use it for shared profile composition such as common or local.
• Consider profile groups when profile combinations become hard to manage.