spring-projects/spring-boot · error · IllegalStateException

Failed to load layers configuration with name '%s': '%s' not

Error message

Failed to load layers configuration with name '%s': '%s' not found

What it means

Thrown by AbstractPackagerMojo.loadLayersConfigurationFromClasspath when a custom layers configuration is requested by name (via <layers><configurationName>...</configurationName></layers>) but the resource META-INF/spring/layers/<name>.xml cannot be found on the plugin's class realm. The plugin resolves named configurations as classpath resources rather than filesystem paths, so a missing resource means the name is wrong or the contributing module did not place the XML correctly. It surfaces as an IllegalStateException during packager configuration.

Source

Thrown at build-plugin/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractPackagerMojo.java:215

	}

	private org.springframework.boot.loader.tools.Layers loadLayersConfiguration() {
		File configuration = this.layers.getConfiguration();
		if (configuration != null) {
			return getCustomLayers(configuration.getAbsolutePath(), () -> new FileInputStream(configuration));
		}
		String configurationName = this.layers.getConfigurationName();
		if (configurationName != null) {
			String location = "META-INF/spring/layers/%s.xml".formatted(configurationName);
			return getCustomLayers(location, () -> loadLayersConfigurationFromClasspath(configurationName, location));
		}
		return IMPLICIT_LAYERS;
	}

	private InputStream loadLayersConfigurationFromClasspath(String name, String location) {
		InputStream in = this.pluginDescriptor.getClassRealm().getResourceAsStream(location);
		if (in == null) {
			throw new IllegalStateException(
					"Failed to load layers configuration with name '%s': '%s' not found".formatted(name, location));
		}
		return in;
	}

	private CustomLayers getCustomLayers(String source, InputStreamSource inputStreamSource) {
		try {
			Document document = getDocumentIfAvailable(inputStreamSource);
			return new CustomLayersProvider().getLayers(document);
		}
		catch (Exception ex) {
			throw new IllegalStateException("Failed to process custom layers configuration " + source, ex);
		}
	}

	private Document getDocumentIfAvailable(InputStreamSource source) throws Exception {
		try (InputStream in = source.getInputStream()) {
			InputSource inputSource = new InputSource(in);

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. Verify the exact value of <configurationName> matches the file basename under META-INF/spring/layers/.
2. Confirm the module or dependency that ships META-INF/spring/layers/<name>.xml is a normal (non-optional, non-excluded) dependency resolvable from the plugin class realm.
3. If you intended a filesystem path instead of a classpath name, use <layers><configuration>/path/to/layers.xml</configuration></layers> instead of configurationName.
4. Inspect the built jar (unzip -l) to confirm the layers.xml is actually packaged at META-INF/spring/layers/.

Example fix

// before (pom.xml)
<layers>
  <configurationName>mylayers</configurationName>
</layers>
// after (match the shipped file name META-INF/spring/layers/my-layers.xml)
<layers>
  <configurationName>my-layers</configurationName>
</layers>

// Before configuring, confirm the classpath resource exists in the built jar
import java.io.IOException;
import java.util.jar.JarFile;

boolean layersResourceExists(File jar, String configurationName) throws IOException {
    String entry = "META-INF/spring/layers/" + configurationName + ".xml";
    try (JarFile jf = new JarFile(jar)) {
        return jf.getEntry(entry) != null;
    }
}

When it happens

Trigger: Setting <layers><configurationName>my-layers</configurationName></layers> in the repackage/build-image configuration when no META-INF/spring/layers/my-layers.xml exists on the plugin classpath. Also triggered if a multi-module build expects a sibling module to contribute the layers.xml via a dependency but that dependency is not on the plugin class realm.

Common situations: Typo in the configurationName; placing the layers.xml under src/main/resources of the application module instead of a dependency that the plugin resolves; upgrading a project that previously used a <configuration> file path and migrating to the named form incorrectly; relying on a library that was supposed to ship the layers.xml but the dependency was marked optional or excluded.

Related errors

• Failed to process custom layers configuration {}
• Could not build classpath
• Unable to build classpath
• A jar or war file is required for building image
• Failed to generate build-info.properties. {}

AI-assisted analysis of spring-projects/spring-boot@5b2dbdbb8b (2026-08-04). Data as JSON: /data/errors/8e0f1e1f8f603718.json. Report an issue: GitHub.