apache/maven · error · InvalidRepositoryException

Cannot find ArtifactRepositoryLayout instance for: %s %s

Error message

Cannot find ArtifactRepositoryLayout instance for: %s %s

What it means

When a repository is created with an explicit layout id, MavenRepositorySystem looks the id up in the injected map of ArtifactRepositoryLayout components and checkLayout throws InvalidRepositoryException 'Cannot find ArtifactRepositoryLayout instance for: <layoutId> <repositoryId>' if none is registered. Out of the box essentially only the 'default' layout exists; any other id must be contributed by a build extension.

Source

Thrown at impl/maven-core/src/main/java/org/apache/maven/bridge/MavenRepositorySystem.java:393

    public ArtifactRepository createArtifactRepository(
            String id,
            String url,
            String layoutId,
            ArtifactRepositoryPolicy snapshots,
            ArtifactRepositoryPolicy releases)
            throws InvalidRepositoryException {
        ArtifactRepositoryLayout layout = layouts.get(layoutId);

        checkLayout(id, layoutId, layout);

        return createArtifactRepository(id, url, layout, snapshots, releases);
    }

    private void checkLayout(String repositoryId, String layoutId, ArtifactRepositoryLayout layout)
            throws InvalidRepositoryException {
        if (layout == null) {
            throw new InvalidRepositoryException(
                    String.format("Cannot find ArtifactRepositoryLayout instance for: %s %s", layoutId, repositoryId),
                    repositoryId);
        }
    }

    public static ArtifactRepository createArtifactRepository(
            String id,
            String url,
            ArtifactRepositoryLayout repositoryLayout,
            ArtifactRepositoryPolicy snapshots,
            ArtifactRepositoryPolicy releases) {
        if (snapshots == null) {
            snapshots = new ArtifactRepositoryPolicy();
        }

        if (releases == null) {
            releases = new ArtifactRepositoryPolicy();
        }

View on GitHub (pinned to e4093d4e12)

Solutions

Remove the `<layout>` element - 'default' is used when omitted and is correct for all modern repositories.
If spelled explicitly, correct it to `default`.
For genuinely custom layouts, declare the extension that registers the layout as a build extension in the same POM.

Example fix

<!-- before -->
<repository>
  <id>corp</id>
  <url>https://repo.corp/m2</url>
  <layout>legacy</layout>
</repository>

<!-- after -->
<repository>
  <id>corp</id>
  <url>https://repo.corp/m2</url>
</repository>

Defensive patterns

Strategy: validation

Validate before calling

Set<String> knownLayouts = Set.of("default"); // layouts registered by build extensions may add more
for (org.apache.maven.model.Repository r : model.getRepositories()) {
    String layout = r.getLayout();
    if (layout != null && !knownLayouts.contains(layout)) {
        throw new IllegalArgumentException("Unknown <layout> " + layout + " on repository " + r.getId());
    }
}

Prevention

Omit `<layout>` for standard Maven 2/3 repositories.
When using a custom layout, declare its provider extension in the same POM.

When it happens

Trigger: `<layout>legacy</layout>` (the old Maven-1-era layout, absent from modern Maven) or a typo like `<layout>defualt</layout>` in a POM/settings repository; a custom corporate layout whose providing extension is not on the classpath.

Common situations: POMs ported forward from the Maven 1/2 era; corporate repository layouts whose extension dependency was dropped during upgrades; misspelled layout ids.

Related errors

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/752fb5d11c311bc0. Report an issue: GitHub.