Introduction

@ConditionalOnProperty is useful for simple exact matches, but it does not support "value1 or value2" logic through a single havingValue attribute. If one property should match either of two values, the usual solutions are @ConditionalOnExpression, a custom Condition, or restructuring the property design.

What @ConditionalOnProperty Actually Supports

A normal case looks like this:

1import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
2import org.springframework.context.annotation.Bean;
3import org.springframework.context.annotation.Configuration;
4
5@Configuration
6public class FeatureConfig {
7
8    @Bean
9    @ConditionalOnProperty(name = "app.mode", havingValue = "value1")
10    public String value1Bean() {
11        return "enabled for value1";
12    }
13}

This condition checks one property against one expected string.

What it does not do is interpret something like:

@ConditionalOnProperty(name = "app.mode", havingValue = "value1,value2")

as an OR condition. That would simply compare the property to the literal string "value1,value2", which is almost never what you want.

Use @ConditionalOnExpression For Simple OR Logic

If the condition is short and readable, @ConditionalOnExpression is often the easiest answer.

1import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
2import org.springframework.context.annotation.Bean;
3import org.springframework.context.annotation.Configuration;
4
5@Configuration
6public class ModeConfig {
7
8    @Bean
9    @ConditionalOnExpression(
10        "'${app.mode:}'.equals('value1') or '${app.mode:}'.equals('value2')"
11    )
12    public String modeSpecificBean() {
13        return "enabled for value1 or value2";
14    }
15}

This works because the expression explicitly spells out the OR condition.

It is fine for small checks, but once the expression starts getting longer, readability drops quickly.

Use A Custom Condition For Clearer Logic

For anything slightly more complex, a custom Condition is cleaner and easier to test.

1import java.util.Set;
2import org.springframework.context.annotation.Condition;
3import org.springframework.context.annotation.ConditionContext;
4import org.springframework.core.type.AnnotatedTypeMetadata;
5
6public class ModeCondition implements Condition {
7
8    private static final Set<String> ALLOWED = Set.of("value1", "value2");
9
10    @Override
11    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
12        String mode = context.getEnvironment().getProperty("app.mode");
13        return mode != null && ALLOWED.contains(mode);
14    }
15}

Use it like this:

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Conditional;
3import org.springframework.context.annotation.Configuration;
4
5@Configuration
6public class CustomConditionalConfig {
7
8    @Bean
9    @Conditional(ModeCondition.class)
10    public String customBean() {
11        return "enabled for selected modes";
12    }
13}

This approach is explicit and scales better than piling logic into a SpEL string.

Another Option: Split The Configuration

Sometimes the real problem is the property design. If you find yourself writing many value-based conditions on one mode string, the configuration may be cleaner as multiple boolean flags or a clearer enum-like setting.

For example, instead of:

app:
  mode: value1

you may prefer:

app:
  feature-x-enabled: true

Then a normal @ConditionalOnProperty becomes enough:

@ConditionalOnProperty(name = "app.feature-x-enabled", havingValue = "true")

This is often easier to understand than encoding several unrelated meanings into one string property.

When Multiple Names Help And When They Do Not

@ConditionalOnProperty does allow multiple property names:

@ConditionalOnProperty(name = {"feature.a", "feature.b"}, havingValue = "true")

But that means all named properties are checked against the same value rule. It does not mean one property can match several alternative values.

That distinction trips people up regularly. Multiple names are about combining several properties, not about OR-matching one property against several candidates.

Choose The Simplest Readable Option

A good rule:

• use @ConditionalOnProperty for one property and one value
• use @ConditionalOnExpression for a small one-off OR
• use a custom Condition when the logic deserves a name

This keeps configuration conditions understandable instead of turning bean registration into hidden string logic.

Common Pitfalls

The biggest mistake is assuming havingValue supports comma-separated alternatives. It does not. Spring treats that as one literal expected value.

Another mistake is reaching for SpEL immediately even when a cleaner custom condition or better property model would be easier to maintain.

People also confuse multiple property names with multiple allowed values. Those are different features with different semantics.

Finally, if the condition logic starts to describe business behavior instead of deployment configuration, it may belong in ordinary application code rather than bean registration.

Summary

• '@ConditionalOnProperty matches one property against one expected value.'
• It does not support "value1 or value2" through a single havingValue.
• Use @ConditionalOnExpression for simple OR checks.
• Use a custom Condition when the logic should be explicit and reusable.
• Sometimes the cleanest fix is redesigning the property itself instead of forcing more conditional syntax.