quarkusio/quarkus · error · RegistryResolutionException

${descriptorResolutionFailureMessage}

Error message

${descriptorResolutionFailureMessage}

What it means

buildRegistryClient() resolves the Quarkus extension registry descriptor artifact through a Maven resolver. When resolution fails with BootstrapMavenException and no Maven mirrors/proxies were applied (the aggregated repos are identical to the registry repos), there is no fallback configuration to retry, so the code wraps the failure in a RegistryResolutionException whose message includes the registry config, resolver repos, and the underlying cause.

Source

Thrown at independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/client/maven/MavenRegistryClientFactory.java:80

        // Determine the original registry Maven repository configuration
        // If the user settings already contain a Maven repository configuration with either an ID matching the registry ID
        // or a URL matching the registry URL, the original Maven resolver will be assumed to be already properly initialized.
        // Otherwise, a new registry Maven repository will be configured and a new resolver will be initialized for the registry.
        final List<RemoteRepository> registryRepos = determineRegistryRepos(config, originalResolver.getRepositories());
        MavenArtifactResolver resolver;
        ArtifactResult result;
        if (!registryRepos.isEmpty()) {
            // first, we try applying the mirrors and proxies found in the user settings
            final List<RemoteRepository> aggregatedRepos = applyMirrorsAndProxies(registryRepos);
            resolver = newResolver(originalResolver, aggregatedRepos, config, log);
            try {
                result = MavenRegistryArtifactResolverWithCleanup.resolveAndCleanupOldTimestampedVersions(resolver,
                        registryDescriptorCoords, cleanupTimestampedArtifacts);
            } catch (BootstrapMavenException e) {
                if (areMatching(registryRepos, aggregatedRepos)) {
                    // the original and aggregated repos are matching, meaning no mirrors/proxies have been applied
                    // there is nothing to fallback to
                    throw new RegistryResolutionException(getDescriptorResolutionFailureMessage(config, resolver, e), e);
                }
                // if the mirror and proxies in the user settings were configured w/o taking the extension registry into account
                // we will warn the user and try the original registry repos as a fallback
                log.warn(getDescriptorResolutionFailureFromMirrorMessage(config, resolver, e, registryRepos));
                resolver = newResolver(originalResolver, registryRepos, config, log);
                try {
                    result = MavenRegistryArtifactResolverWithCleanup.resolveAndCleanupOldTimestampedVersions(resolver,
                            registryDescriptorCoords, cleanupTimestampedArtifacts);
                } catch (BootstrapMavenException e1) {
                    throw new RegistryResolutionException(getDescriptorResolutionFailureMessage(config, resolver, e));
                }
            }
        } else {
            resolver = newResolver(originalResolver, originalResolver.getRepositories(), config, log);
            try {
                result = MavenRegistryArtifactResolverWithCleanup.resolveAndCleanupOldTimestampedVersions(resolver,
                        registryDescriptorCoords, cleanupTimestampedArtifacts);
            } catch (BootstrapMavenException e) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify network connectivity to the registry repository URL shown in the cause (curl the repo URL/descriptor path); fix proxies/VPN/firewall if blocked
2. Check the registry id/url in your Quarkus registry config and ~/.m2/settings.xml for typos, and that the descriptor coordinates/version actually exist in the registry
3. If a corporate mirror is intended, configure it so it actually matches/applies to the registry repository (mirrorOf settings) — currently the code detected no mirror was applied
4. Add credentials for the registry repository in settings.xml servers section if the registry requires authentication
5. Clear the corrupted local cache entry for the descriptor (delete the artifact dir under ~/.m2/repository) and retry

Example fix

// before (settings.xml mirror that misses the registry)
<mirror><id>corp</id><mirrorOf>external:*</mirrorOf>...</mirror> // but repo blocked
// after: ensure registry reachable or explicitly mirror it
<mirror><id>corp</id><mirrorOf>quarkus-registry</mirrorOf><url>https://corp-mirror.example/quarkus/registry</url></mirror>

// preflight: check reachability of the registry repo before building the client
URL url = new URI(registryConfig.getUrl()).toURL();
HttpURLConnection c = (HttpURLConnection) url.openConnection();
c.setConnectTimeout(5000);
if (c.getResponseCode() >= 400) throw new IllegalStateException("Registry unreachable: " + url);

try {
    RegistryClient client = factory.buildRegistryClient(config);
} catch (RegistryResolutionException e) {
    log.errorf(e, "Cannot resolve registry descriptor for %s; check URL/network/credentials", config.getId());
    // fall back to cached/offline mode or abort with a clear user message
}

When it happens

Trigger: Calling buildRegistryClient(config) where the registry descriptor artifact (e.g. a platform descriptors JSON) cannot be downloaded from the configured registry repository and determineRegistryRepos() found registry repos to configure but no mirrors/proxies changed them; the resolver's attempt (network error, HTTP 404, auth failure) throws BootstrapMavenException.

Common situations: Registry URL typo or wrong host in quarkus.application/extension registries config or settings.xml; offline/air-gapped machine or corporate firewall blocking repo.quarkus.io; missing or invalid credentials in settings.xml for a private registry; descriptor artifact removed or registry version nonexistent; corrupted local Maven cache.

Related errors

• Failed to resolve Quarkus extension catalog
• Failed to resolve the extension catalog for stream '${stream
• Failed to resolve the available updates
• Failed to list extension categories
• Failed to initialize Quarkus Maven extension manager

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