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

[graemerocher]

Fixes #11703

AI was used in the production for this PR.

Summary

• Introduces a configurable strategy for handling duplicate config files on the classpath (e.g. application.yml, application.properties).
• Changes the default behavior to fail fast with a clear ConfigurationException listing all conflicting resource locations.
• Adds options to keep prior behavior (FIRST_MATCH) or MERGE_ALL duplicate resources (with optional mergeOrder by jar name patterns).

Key changes

• New API: ConfigurationLoadStrategy / ConfigurationLoadStrategyType
• New builder hook: ApplicationContextBuilder#configurationLoadingStrategy(...) (propagated through Micronaut)
• Environment loading updates to detect duplicates and apply the selected strategy
• Tests covering default fail-fast, FIRST_MATCH, MERGE_ALL (+ mergeOrder), and env-specific resources
• Docs updates + breaking change note (v5) using snippet-backed examples

Migration / behavior change

If you relied on “first match wins” when duplicates exist, configure:

ApplicationContext.builder()
    .configurationLoadingStrategy(s -> s.type(ConfigurationLoadStrategyType.FIRST_MATCH))
    .start();

• Expose configuration load strategy on builders
• Fix constant property source loader initialization
• Handle duplicate configuration resources
• Add tests for configuration loading strategy
• Document duplicate configuration resource handling

[Copilot]

Pull request overview

Adds a configurable configuration-resource loading strategy to Micronaut so duplicate config files on the classpath can either fail fast (new default), fall back to first-match behavior, or be merged deterministically (optionally with merge ordering).

Changes:

• Introduces ConfigurationLoadStrategy / ConfigurationLoadStrategyType and exposes it via ApplicationContextBuilder (and Micronaut) to control duplicate handling.
• Updates DefaultEnvironment config loading to detect duplicates, optionally warn, fail fast, or merge resources (with optional regex-based mergeOrder).
• Adds docs snippets + guide updates and new Spock tests for the new behavior.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test-suite/src/test/java/io/micronaut/docs/context/env/ConfigurationLoadStrategySnippet.java	Java docs snippet demonstrating strategy configuration
test-suite-kotlin/src/test/kotlin/io/micronaut/docs/context/env/ConfigurationLoadStrategySnippet.kt	Kotlin docs snippet demonstrating strategy configuration
test-suite-groovy/src/test/groovy/io/micronaut/docs/context/env/ConfigurationLoadStrategySnippet.groovy	Groovy docs snippet demonstrating strategy configuration
test-suite-property-source/src/test/groovy/io/micronaut/context/env/ConstantPropertySourceSpec.groovy	Updates test setup to explicitly restore legacy FIRST_MATCH behavior
test-suite-property-source/src/test/groovy/io/micronaut/context/env/ConfigurationLoadStrategySpec.groovy	New tests for default fail-fast, FIRST_MATCH, MERGE_ALL, mergeOrder, env-specific duplicates
src/main/docs/guide/config/propertySource.adoc	Documents duplicate configuration resource handling and strategy options
src/main/docs/guide/appendix/breaks.adoc	Adds Micronaut 5 breaking change note for default fail-fast behavior
inject/src/main/java/io/micronaut/context/env/DefaultEnvironment.java	Implements duplicate detection + strategy application during config loading
inject/src/main/java/io/micronaut/context/env/ConstantPropertySourceLoader.java	Adjusts constant property source loader initialization behavior
inject/src/main/java/io/micronaut/context/env/ConfigurationLoadStrategyType.java	New enum defining strategy types
inject/src/main/java/io/micronaut/context/env/ConfigurationLoadStrategy.java	New record + builder defining strategy configuration
inject/src/main/java/io/micronaut/context/DefaultApplicationContextBuilder.java	Stores/applies strategy configured via builder hook
inject/src/main/java/io/micronaut/context/ApplicationContextConfiguration.java	Adds strategy to context configuration API with default
inject/src/main/java/io/micronaut/context/ApplicationContextBuilder.java	Adds builder hook for configuring strategy
context/src/main/java/io/micronaut/runtime/Micronaut.java	Propagates new builder hook through Micronaut

[graemerocher]

@copilot open a new pull request to apply changes based on the comments in this thread

[Copilot]

@graemerocher I've opened a new pull request, #12384, to work on those changes. Once the pull request is ready, I'll request review from you.

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ graemerocher
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[graemerocher]

the test failure is unrelated

[dstepanov]

I would prefer for this to be implemented in the same way as Spring has it with classpath*:

classpath: - Locates only the first resource found at the specified path within the classpath.

classpath*: - Locates all resources that match the given name across all classpath entries (directories and JARs).

And this can be used with .overrideConfigLocations("classpath*:/", "file:config/").
The logic should be put somewhere in DefaultClassPathResourceLoader with something like Stream<URL> getResources(String name, boolean includeAll);

[graemerocher]

I don't understand, in this case the user doesn't specify where or how config is loaded. If there are duplicate application.properties it is unknown which is loaded which causes weird behaviour like having to search through your jar files for the duplicate. We need a solution to this in 5.x that is easier to debug

[sdelamo]

I think the feature is useful but the PR does not contain tests for the new logic in DefaultEnvironment::loadPropertySourceFromAbstractLoader

[sonarqubecloud]

Quality Gate failed

Failed conditions
51.8% Coverage on New Code (required ≥ 70%)
3 New Bugs (required ≤ 0)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[dstepanov]

Can you move all of it into a new method to ClassPathResourceLoader with an option to merge of fail? I don't think it should be included here

[graemerocher]

I don't understand, ClassPathResourceLoader is in the core module and has nothing to do with environment configuration. Why would it go there?

[dstepanov]

Because the main issue is about the classpath files being loaded and the strategies resolving the conflicts etc. I don't think the DefaultEnvironment should be responsible for that logic. Considering there might be different consumers of the classpath files that might also want to react to similar problems. One of them being reported is actually the database flyway migrations being in multiple jars. Not sure if it's mostly about the properties or if some of the frameworks what to load multiple different files/configurations of the same name from the classpath.