application.yml from Libraries Can Override or Be Silently Ignored — No Merging or Warning

[tmellanxt]

Expected Behavior

In this scenario, where a Micronaut application defines application.yaml and a library dependency provides its own application.yml, the expected behavior is:

1. The application's configuration (application.yaml) should always take precedence.
   This aligns with developer expectations — the application's own config should never be overridden silently by a transitive library dependency.

2. Library configuration files should be loaded optionally and with transparency.
   If a library provides its own application.yml, it may contain useful default values. These should be:

   • Merged after the application config (lower precedence)
   • Only if key conflicts don't exist
   • Accompanied by a log message indicating their source and loading behavior

3. When multiple application.yml or .yaml files are found, Micronaut should:

   • Merge them (with deterministic ordering and documented rules), or
   • Emit a warning stating that only one was used, and which one

4. Ideally, Micronaut would support a configurable loading strategy, so developers can explicitly opt into:

   • FIRST_MATCH (current behavior)
   • MERGE_ALL
   • FAIL_ON_DUPLICATE
   • Possibly others (e.g., APP_ONLY, APP_OVERRIDES_LIBS)

This approach ensures application authors retain full control over configuration while allowing library authors to provide sensible defaults without risk of overriding or being silently ignored.

Actual Behaviour

We created a reproducible Gradle multi-module Micronaut project with:

• A main app module that defines application.yaml
• A library module that defines its own application.yml

Expected: The application's config (application.yaml) should be loaded and take precedence.
Actual: The application's config is silently ignored — only the library's application.yml is used.

There are no logs, warnings, or exceptions indicating this override has occurred.

---

🔬 Why This Happens: Deep Dive into Micronaut’s YamlPropertySourceLoader

The root cause lies in the YamlPropertySourceLoader, which extends AbstractPropertySourceLoader. Here’s the key method in AbstractPropertySourceLoader:

private Optional<PropertySource> load(ResourceLoader resourceLoader, String fileName, int order) {
    if (this.isEnabled()) {
        Set<String> extensions = this.getExtensions(); // e.g., ["yml", "yaml"]
        Iterator<String> var5 = extensions.iterator();

        while (var5.hasNext()) {
            String ext = var5.next();
            String fileExt = fileName + "." + ext; // Tries application.yml then application.yaml

            Map<String, Object> finalMap = this.loadProperties(resourceLoader, fileName, fileExt);
            if (!finalMap.isEmpty()) {
                return Optional.of(this.createPropertySource(fileName, finalMap, order)); // First match wins
            }
        }
    }

    return Optional.empty();
}

### Steps To Reproduce


> **Prerequisite:** Ensure Java 21 is installed and configured as the active JDK.

1. **Clone the Repository:**
   ```bash
   git clone <repository-url>
   cd <repository-directory>

2. Build the Project:

   ./gradlew build

3. Run the Application:

   ./gradlew :app:run

4. Observe the Output:

   Notice that the configuration value from
   app/src/main/resources/application.yaml is not printed.
   Instead, the value from
   utilities/src/main/resources/application.yml is used.

5. Modify the Project:

   Open app/build.gradle and comment out the following line:

   implementation(project(":utilities"))

6. Rebuild and Rerun the Application:

   ./gradlew build
   ./gradlew :app:run

7. Observe the Output Again:

   Now, the configuration value from
   app/src/main/resources/application.yaml is printed as expected.

---

These steps demonstrate the issue where the application.yml from the utilities module overrides the application.yaml from the app module.

Environment Information

MacOS: 15.3.2 (24D81)
Java 21
Built tool: gradle

Example Application

https://github.com/tmellanxt/micronaut-yaml-bug

Version

4.7.6

🙋‍♂️ Contributor Statement

I am happy to contribute a fix for this issue and would appreciate guidance from the Micronaut team on the preferred direction. Specifically:

• I am in favor of introducing a configurable loading strategy, such as:
  • micronaut.config.load-strategy=FIRST_MATCH | MERGE_ALL | FAIL_ON_DUPLICATE, etc.
• I’d be glad to prototype a solution, update documentation, and write tests — but would like confirmation on which strategy or direction aligns with project goals before submitting a PR.

Additionally, it’s worth noting that this issue affects not just applications being overridden by libraries, but also cases where multiple libraries provide their own application.yml. In those cases, only one is loaded, and the rest are silently ignored, which can also break expected behavior unless libraries explicitly configure environment profiles or load configs differently.

[graemerocher]

A configurable loading strategy seems reasonable. We cannot include breaking changes to the default behaviour.

[dstepanov]

The solution here would be add a special classpath*: config location like it's in Spring and you can override the default one Arrays.asList("classpath:/", "file:config/")

[graemerocher]

not sure if that is enough since it then depends on class path order which is loaded first

[dstepanov]

I think you need to scan jars in that case, so it's slower but allows to load all the duplicates. My idea is not to have it by default but let the user override the default config location strategy.

[Jarvx]

The following test was generated by AI to help validate and reproduce the behavior described here.
Please note that while the test is automatically generated, it has been verified to compile and execute against the current project (v4.10x).

Test files(s)

src/test/java/io/micronaut/context/env/YamlPropertySourceLoaderPrecedenceTest.java

package io.micronaut.context.env;

import io.micronaut.context.ApplicationContext;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;

import java.net.URL;
import java.net.URLClassLoader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Optional;

import static org.junit.jupiter.api.Assertions.*;

/**
 * Reproduces issue where a library's application.yml (or application-<env>.yml) takes precedence over an
 * application's application.yaml (or application-<env>.yaml) due to first-match loading in
 * AbstractPropertySourceLoader / classpath order.
 *
 * Expected by users: the application's configuration should win over library defaults and/or be merged.
 * Actual behavior (current): library wins when it appears earlier on the classpath for the first extension checked.
 *
 * The test encodes the expected behavior (app should win). It currently FAILS, reproducing the issue.
 */
class YamlPropertySourceLoaderPrecedenceTest {

    @TempDir
    Path tmp;

    @Test
    void applicationYamlShouldOverrideLibraryApplicationYmlButCurrentlyDoesNot() throws Exception {
        // Use a profile-specific file name to avoid interference with any other test resources on the parent classpath
        final String env = "yaml-override-repro";
        final String base = "application-" + env;

        // Prepare two classpath roots: lib (with yml) first, then app (with yaml)
        Path libDir = Files.createDirectory(tmp.resolve("lib"));
        Path appDir = Files.createDirectory(tmp.resolve("app"));

        // Library provides application-<env>.yml
        Files.write(
                libDir.resolve(base + ".yml"),
                ("repro:\n" +
                 "  value: lib\n" +
                 "libOnly: yes\n").getBytes(StandardCharsets.UTF_8)
        );

        // Application provides application-<env>.yaml
        Files.write(
                appDir.resolve(base + ".yaml"),
                ("repro:\n" +
                 "  value: app\n" +
                 "appOnly: yes\n").getBytes(StandardCharsets.UTF_8)
        );

        // ClassLoader with library first, then application — simulates dependency preceding the app on classpath
        try (URLClassLoader cl = new URLClassLoader(new URL[]{libDir.toUri().toURL(), appDir.toUri().toURL()}, this.getClass().getClassLoader())) {
            try (ApplicationContext ctx = ApplicationContext.builder()
                    .classLoader(cl)
                    .deduceEnvironment(false)
                    .environments(env)
                    .start()) {
                Optional<String> value = ctx.getProperty("repro.value", String.class);
                assertTrue(value.isPresent(), "Expected repro.value to be present");

                // Assertion reflects expected behavior (application should override library). This currently FAILS
                // because the library's application-<env>.yml is the first match and is used exclusively.
                assertEquals("app", value.get(), "Application configuration should override library configuration");

                // Optional: if merging were supported, both unique keys would be present.
                assertEquals(Optional.of("yes"), ctx.getProperty("appOnly", String.class), "Expected application's unique key to be present");
            }
        }
    }
}

Test command

./gradlew :test-suite:test

Why This Test Reproduces the Issue

The test YamlPropertySourceLoaderPrecedenceTest explicitly checks that a property from the application's application.yaml should be present/override the library’s application.yml. It fails with an assertion indicating the property is not present, implying the app’s YAML was ignored and only the library’s config was used. This aligns with the reported issue of FIRST_MATCH behavior causing the application config to be overridden/ignored without warnings. The single failing test directly targets this behavior, confirming reproduction.