quarkusio/quarkus · error · IllegalStateException

${causedByMessages}

Error message

${causedByMessages}

What it means

QuarkusProjectHelper.artifactResolver() lazily builds a shared MavenArtifactResolver. If bootstrap fails with BootstrapMavenException (bad Maven settings, unresolvable local repo, invalid configuration), it builds an IllegalStateException whose message is 'Failed to initialize the Maven artifact resolver' followed by every non-blank message from the cause chain (the ${causedByMessages} placeholder).

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/devtools/project/QuarkusProjectHelper.java:251

        if (artifactResolver == null) {
            try {
                artifactResolver = MavenArtifactResolver.builder()
                        .setArtifactTransferLogging(toolsConfig().isDebug())
                        .setWorkspaceDiscovery(false)
                        .build();
            } catch (BootstrapMavenException e) {
                StringBuilder messages = new StringBuilder("Failed to initialize the Maven artifact resolver");
                Throwable current = e;
                while (null != current) {
                    if (null != current.getMessage() && !current.getMessage().isBlank()) {
                        messages
                                .append("\n")
                                .append(current.getMessage());
                    }

                    current = current.getCause();
                }
                throw new IllegalStateException(messages.toString().trim(), e);
            }
        }
        return artifactResolver;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the full multi-line message — each appended line is a cause message pinpointing the failing settings/repo.
2. Validate ~/.m2/settings.xml (and any -s custom settings) as well-formed XML with valid repository/mirror/proxy entries.
3. Ensure the local Maven repository path exists and is writable, or fix the localRepository setting.
4. Run mvn -X on a trivial project with the same settings to reproduce and diagnose the resolver failure.

Example fix

// before (settings.xml)
<localRepository>/nonexistent/path/repo</localRepository>
// after
<localRepository>${user.home}/.m2/repository</localRepository>

// validate settings.xml parses before bootstrapping the resolver
try {
    javax.xml.XMLConstants.class.getName();
    var f = javax.xml.parsers.DocumentBuilderFactory.newInstance();
    f.newDocumentBuilder().parse(new File(System.getProperty("user.home"), ".m2/settings.xml"));
} catch (Exception e) { /* fix settings.xml first */ }

try {
    MavenArtifactResolver r = QuarkusProjectHelper.artifactResolver();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to initialize the Maven artifact resolver")) {
        // each line of e.getMessage() is one cause message — surface them all to the user
    }
}

When it happens

Trigger: Any call to QuarkusProjectHelper.artifactResolver() (directly, or indirectly via getCatalogResolver/getExtensionCatalog) when MavenArtifactResolver.builder().build() throws BootstrapMavenException — e.g. unparsable ~/.m2/settings.xml, invalid localRepository path, or unresolvable parent/imported POMs during workspace discovery setup.

Common situations: Corrupted or hand-edited ~/.m2/settings.xml (malformed XML); MAVEN_OPTS/user settings pointing at a missing or read-only local repository; corporate proxies requiring credentials; incompatible Maven model building when the current directory or project POM is broken.

Related errors

• Unsupported format: ${format}
• Could not resolve POM for
• Either the `extension` or `extensions` parameter must be set
• Cannot specify both class and method name
• The project artifact's extension is '${extension}' while thi

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/3dc1ed6f707a2804. Report an issue: GitHub.