quarkusio/quarkus · error · IllegalStateException

Failed to intialize the default Maven artifact resolver

Error message

Failed to intialize the default Maven artifact resolver

What it means

Thrown by ExtensionCatalogResolver's config-completion step when building the default MavenArtifactResolver fails with a BootstrapMavenException. This means the embedded Maven resolver could not be initialized — usually invalid Maven settings, a broken local repository, or unresolvable settings configuration.

Source

Thrown at independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/ExtensionCatalogResolver.java:107

            buildRegistryClients();
            return ExtensionCatalogResolver.this;
        }

        private void completeConfig() {
            if (config == null) {
                config = RegistriesConfigLocator.resolveConfig();
            }
            if (log == null) {
                log = config.isDebug() ? MessageWriter.debug() : MessageWriter.info();
            }
            if (artifactResolver == null) {
                try {
                    artifactResolver = MavenArtifactResolver.builder()
                            .setWorkspaceDiscovery(false)
                            .setArtifactTransferLogging(config.isDebug())
                            .build();
                } catch (BootstrapMavenException e) {
                    throw new IllegalStateException("Failed to intialize the default Maven artifact resolver", e);
                }
            }
        }

        private void buildRegistryClients() throws RegistryResolutionException {
            registries = new ArrayList<>(config.getRegistries().size());
            for (RegistryConfig config : config.getRegistries()) {
                if (!config.isEnabled()) {
                    continue;
                }
                final RegistryClientFactory clientFactory = getClientFactory(config);
                registries
                        .add(new RegistryExtensionResolver(clientFactory.buildRegistryClient(config), log));
            }
        }

        private RegistryClientFactory getClientFactory(RegistryConfig config) {
            if (config.getExtra().isEmpty()) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Validate ~/.m2/settings.xml parses and has valid URLs (mvn help:effective-settings)
2. Check the error's cause for the exact settings element that failed
3. Fix or temporarily rename settings.xml to isolate the problem
4. Ensure the local Maven repository path exists and is writable

Example fix

// before: settings.xml
<mirror><url>htp:/bad-url</url></mirror>
// after
<mirror>
  <id>central</id>
  <url>https://repo.maven.apache.org/maven2</url>
  <mirrorOf>central</mirrorOf>
</mirror>

// Validate Maven settings before building the resolver
Path settings = Path.of(System.getProperty("user.home"), ".m2", "settings.xml");
if (Files.exists(settings)) {
    new XmlSlurper().parse(settings.toFile()); // or SAXParser: throws if malformed
}

try {
    resolver.build();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Failed to intialize the default Maven artifact resolver")) {
        // inspect e.getCause() (BootstrapMavenException) for the offending settings element
    }
    throw e;
}

When it happens

Trigger: Calling build() on an ExtensionCatalogResolver with no custom artifact resolver, where MavenArtifactResolver.builder()...build() throws because settings.xml is invalid, the local repo path is bad, or Maven profile/property resolution fails.

Common situations: Malformed ~/.m2/settings.xml; invalid mirror/repository URLs; unreadable or corrupted local repository; MAVEN_OPTS/-Dmaven.* flags conflicting; missing MAVEN_HOME settings resolution.

Related errors

• Unsupported format: ${format}
• 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
• Specifying a stream requires the Quarkus extension registry

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