Fail fast on duplicate configuration resources (with configurable merge/first-match)

context/src/main/java/io/micronaut/runtime/Micronaut.java

@@ -23,6 +23,7 @@
 import io.micronaut.context.banner.MicronautBanner;
 import io.micronaut.context.banner.ResourceBanner;
 import io.micronaut.context.env.Environment;
+import io.micronaut.context.env.ConfigurationLoadStrategy;
 import io.micronaut.context.env.PropertySource;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -37,6 +38,7 @@
 import java.util.Map;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
+import java.util.function.Consumer;
 import java.util.function.Function;
 
 import static io.micronaut.core.reflect.ReflectionUtils.EMPTY_CLASS_ARRAY;
@@ -280,6 +282,11 @@ public Micronaut environments(String @Nullable ... environments) {
         return (Micronaut) super.environments(environments);
     }
 
+    @Override
+    public Micronaut configurationLoadingStrategy(Consumer<ConfigurationLoadStrategy.Builder> builderConsumer) {
+        return (Micronaut) super.configurationLoadingStrategy(builderConsumer);
+    }
+
     @Override
     public Micronaut defaultEnvironments(String @Nullable ... environments) {
         return (Micronaut) super.defaultEnvironments(environments);

inject/src/main/java/io/micronaut/context/ApplicationContextBuilder.java

@@ -16,6 +16,7 @@
 package io.micronaut.context;
 
 import io.micronaut.context.annotation.ConfigurationReader;
+import io.micronaut.context.env.ConfigurationLoadStrategy;
 import io.micronaut.context.env.PropertySource;
 import io.micronaut.context.env.PropertySourcesLocator;
 import io.micronaut.core.io.scan.ClassPathResourceLoader;
@@ -28,6 +29,7 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
+import java.util.function.Consumer;
 
 /**
  * An interface for building an application context.
@@ -109,6 +111,17 @@ default ApplicationContextBuilder enableDefaultPropertySources(boolean areEnable
         return this;
     }
 
+    /**
+     * Configure how Micronaut loads configuration resources when duplicates exist on the classpath.
+     *
+     * @param builderConsumer The strategy builder customizer
+     * @return This builder
+     * @since 5.0.0
+     */
+    default ApplicationContextBuilder configurationLoadingStrategy(Consumer<ConfigurationLoadStrategy.Builder> builderConsumer) {
+        return this;
+    }
+
     /**
      * Specifies to eager init the given annotated types.
      *

inject/src/main/java/io/micronaut/context/ApplicationContextConfiguration.java

@@ -17,6 +17,7 @@
 
 import io.micronaut.context.env.EnvironmentNamesDeducer;
 import io.micronaut.context.env.EnvironmentPackagesDeducer;
+import io.micronaut.context.env.ConfigurationLoadStrategy;
 import io.micronaut.context.env.PropertySourcesLocator;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
@@ -207,4 +208,14 @@ default Collection<PropertySourcesLocator> getPropertySourcesLocators() {
         return Collections.emptyList();
     }
 
+    /**
+     * Defines how configuration resources are loaded when duplicates exist on the classpath.
+     *
+     * @return The configuration loading strategy
+     * @since 5.0.0
+     */
+    default ConfigurationLoadStrategy getConfigurationLoadingStrategy() {
+        return ConfigurationLoadStrategy.defaultStrategy();
+    }
+
 }

inject/src/main/java/io/micronaut/context/DefaultApplicationContextBuilder.java

@@ -16,6 +16,7 @@
 package io.micronaut.context;
 
 import io.micronaut.context.env.CommandLinePropertySource;
+import io.micronaut.context.env.ConfigurationLoadStrategy;
 import io.micronaut.context.env.Environment;
 import io.micronaut.context.env.PropertySource;
 import io.micronaut.context.env.PropertySourcesLocator;
@@ -26,6 +27,7 @@
 import io.micronaut.core.io.scan.ClassPathResourceLoader;
 import io.micronaut.core.io.service.SoftServiceLoader;
 import io.micronaut.core.order.OrderUtil;
+import io.micronaut.core.util.ArgumentUtils;
 import io.micronaut.core.util.StringUtils;
 import io.micronaut.inject.BeanConfiguration;
 import io.micronaut.inject.QualifiedBeanType;
@@ -41,6 +43,7 @@
 import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
+import java.util.function.Consumer;
 import java.util.function.Predicate;
 
 import static io.micronaut.core.util.StringUtils.EMPTY_STRING_ARRAY;
@@ -85,6 +88,7 @@ public class DefaultApplicationContextBuilder implements ApplicationContextBuild
     private Boolean bootstrapEnvironment = null;
     private boolean enableDefaultPropertySources = true;
     private BeanResolutionTraceConfiguration traceConfiguration = new BeanResolutionTraceConfiguration();
+    private ConfigurationLoadStrategy configurationLoadStrategy = ConfigurationLoadStrategy.defaultStrategy();
     private BeanDefinitionsProvider beanDefinitionsProvider = new DefaultBeanDefinitionsProvider();
     private boolean eagerBeansEnabled = true;
     private boolean eventsEnabled = true;
@@ -122,6 +126,11 @@ public BeanResolutionTraceConfiguration getTraceConfiguration() {
         return this.traceConfiguration;
     }
 
+    @Override
+    public ConfigurationLoadStrategy getConfigurationLoadingStrategy() {
+        return configurationLoadStrategy;
+    }
+
     private ClassLoader resolveClassLoader() {
         final ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
         if (contextClassLoader != null) {
@@ -146,6 +155,15 @@ public ApplicationContextBuilder enableDefaultPropertySources(boolean areEnabled
         return this;
     }
 
+    @Override
+    public ApplicationContextBuilder configurationLoadingStrategy(Consumer<ConfigurationLoadStrategy.Builder> builderConsumer) {
+        ArgumentUtils.requireNonNull("builderConsumer", builderConsumer);
+        ConfigurationLoadStrategy.Builder builder = ConfigurationLoadStrategy.builder();
+        builderConsumer.accept(builder);
+        this.configurationLoadStrategy = builder.build();
+        return this;
+    }
+
     @Override
     public boolean isEnableDefaultPropertySources() {
         return enableDefaultPropertySources;

inject/src/main/java/io/micronaut/context/env/ConfigurationLoadStrategy.java

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2017-2026 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.context.env;
+
+import io.micronaut.context.exceptions.ConfigurationException;
+import org.jspecify.annotations.NullMarked;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Configuration resource loading strategy.
+ *
+ * @param type             The strategy type. Defaults to {@link ConfigurationLoadStrategyType#FAIL_ON_DUPLICATE}.
+ * @param warnOnDuplicates Whether to warn when duplicates are found. Applies only to {@link ConfigurationLoadStrategyType#FIRST_MATCH}.
+ * @param mergeOrder       Artifact name regex patterns used to order resources before merging. Applies only to {@link ConfigurationLoadStrategyType#MERGE_ALL}.
+ * @since 5.0.0
+ */
+@NullMarked
+public record ConfigurationLoadStrategy(
+    ConfigurationLoadStrategyType type,
+    boolean warnOnDuplicates,
+    List<String> mergeOrder
+) {
+    /**
+     * Default strategy.
+     */
+    public static ConfigurationLoadStrategy defaultStrategy() {
+        return builder().build();
+    }
+
+    /**
+     * @return A new {@link Builder}.
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public ConfigurationLoadStrategy {
+        if (type == null) {
+            type = ConfigurationLoadStrategyType.FAIL_ON_DUPLICATE;
+        }
+        if (mergeOrder == null) {
+            mergeOrder = List.of();
+        } else {
+            // Always create a defensive copy to prevent external mutation
+            mergeOrder = new ArrayList<>(mergeOrder);
+        }
+
+        if (!mergeOrder.isEmpty() && type != ConfigurationLoadStrategyType.MERGE_ALL) {
+            throw new ConfigurationException("mergeOrder is only supported when configuration loading strategy type is MERGE_ALL");
+        }
+
+        mergeOrder = Collections.unmodifiableList(mergeOrder);
+    }
+
+    /**
+     * Mutable builder for {@link ConfigurationLoadStrategy}.
+     */
+    @NullMarked
+    public static final class Builder {
+        private ConfigurationLoadStrategyType type = ConfigurationLoadStrategyType.FAIL_ON_DUPLICATE;
+        private boolean warnOnDuplicates = true;
+        private List<String> mergeOrder = List.of();
+
+        public Builder type(ConfigurationLoadStrategyType type) {
+            this.type = Objects.requireNonNullElse(type, ConfigurationLoadStrategyType.FAIL_ON_DUPLICATE);
+            return this;
+        }
+
+        public Builder warnOnDuplicates(boolean warnOnDuplicates) {
+            this.warnOnDuplicates = warnOnDuplicates;
+            return this;
+        }
+
+        public Builder mergeOrder(List<String> mergeOrder) {
+            this.mergeOrder = Objects.requireNonNullElse(mergeOrder, List.of());
+            return this;
+        }
+
+        public Builder mergeOrder(String... mergeOrder) {
+            if (mergeOrder == null || mergeOrder.length == 0) {
+                this.mergeOrder = List.of();
+            } else {
+                this.mergeOrder = List.of(mergeOrder);
+            }
+            return this;
+        }
+
+        public ConfigurationLoadStrategy build() {
+            return new ConfigurationLoadStrategy(type, warnOnDuplicates, mergeOrder);
+        }
+    }
+}

inject/src/main/java/io/micronaut/context/env/ConfigurationLoadStrategyType.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2017-2026 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.micronaut.context.env;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Defines how Micronaut should behave when the same configuration resource (for example
+ * {@code application.yml} or {@code application.properties}) is found more than once on the classpath.
+ *
+ * @since 5.0.0
+ */
+@NullMarked
+public enum ConfigurationLoadStrategyType {
+    /**
+     * The first matching resource is used. Duplicates may be logged as a warning.
+     */
+    FIRST_MATCH,
+
+    /**
+     * All matching resources are read and merged in the configured order.
+     */
+    MERGE_ALL,
+
+    /**
+     * Fail fast if duplicate configuration resources are detected.
+     */
+    FAIL_ON_DUPLICATE
+}

inject/src/main/java/io/micronaut/context/env/ConstantPropertySourceLoader.java

@@ -39,22 +39,20 @@
 @Internal
 public final class ConstantPropertySourceLoader implements PropertySourceLoader {
 
-    private final List<PropertySource> constantPropertySources;
-
-    public ConstantPropertySourceLoader() {
-        constantPropertySources = StaticOptimizations.get(ConstantPropertySources.class)
-        .map(ConstantPropertySources::getSources)
-        .orElse(Collections.emptyList());
+    private static List<PropertySource> getConstantPropertySources() {
+        return StaticOptimizations.get(ConstantPropertySources.class)
+            .map(ConstantPropertySources::getSources)
+            .orElse(Collections.emptyList());
     }
 
     @Override
     public boolean isEnabled() {
-        return !constantPropertySources.isEmpty();
+        return !getConstantPropertySources().isEmpty();
     }
 
     @Override
     public Optional<PropertySource> load(String resourceName, ResourceLoader resourceLoader) {
-        for (PropertySource p : constantPropertySources) {
+        for (PropertySource p : getConstantPropertySources()) {
             if (p.getName().equals(resourceName)) {
                 return Optional.of(p);
             }
@@ -64,7 +62,7 @@ public Optional<PropertySource> load(String resourceName, ResourceLoader resourc
 
     @Override
     public Optional<PropertySource> loadEnv(String resourceName, ResourceLoader resourceLoader, ActiveEnvironment activeEnvironment) {
-        for (PropertySource p : constantPropertySources) {
+        for (PropertySource p : getConstantPropertySources()) {
             if (p.getName().equals(resourceName + "-" + activeEnvironment.getName())) {
                 return Optional.of(p);
             }