quarkusio/quarkus · error · RuntimeException

Failed to resolve the recommended Quarkus extension catalog

Error message

Failed to resolve the recommended Quarkus extension catalog from the configured extension registries

What it means

The quarkusUpdate Gradle task resolves the recommended Quarkus extension catalog from the configured extension registries (e.g. registry.quarkus.io) via ExtensionCatalogResolver. This RuntimeException wraps RegistryResolutionException thrown when the registries cannot be reached or return invalid data, so the update recommendations cannot be computed.

Source

Thrown at devtools/gradle/gradle-application-plugin/src/main/java/io/quarkus/gradle/tasks/QuarkusUpdate.java:165

        final QuarkusProject quarkusProject = getQuarkusProject(false);
        final ExtensionCatalog targetCatalog;
        try {
            if (targetPlatformVersion != null) {
                var targetPrimaryBom = getPrimaryBom(quarkusProject.getExtensionsCatalog());
                targetPrimaryBom = ArtifactCoords.pom(targetPrimaryBom.getGroupId(), targetPrimaryBom.getArtifactId(),
                        targetPlatformVersion);
                targetCatalog = getExtensionCatalogResolver(quarkusProject.log())
                        .resolveExtensionCatalog(List.of(targetPrimaryBom));
            } else if (targetStreamId != null) {
                var platformStream = PlatformStreamCoords.fromString(targetStreamId);
                targetCatalog = getExtensionCatalogResolver(quarkusProject.log()).resolveExtensionCatalog(platformStream);
                targetPlatformVersion = getPrimaryBom(targetCatalog).getVersion();
            } else {
                targetCatalog = getExtensionCatalogResolver(quarkusProject.log()).resolveExtensionCatalog();
                targetPlatformVersion = getPrimaryBom(targetCatalog).getVersion();
            }
        } catch (RegistryResolutionException e) {
            throw new RuntimeException(
                    "Failed to resolve the recommended Quarkus extension catalog from the configured extension registries", e);
        }

        final UpdateProject invoker = new UpdateProject(quarkusProject);
        invoker.targetCatalog(targetCatalog);
        if (rewriteQuarkusUpdateRecipes != null) {
            invoker.rewriteQuarkusUpdateRecipes(rewriteQuarkusUpdateRecipes);
        }
        if (rewriteAdditionalUpdateRecipes != null) {
            invoker.rewriteAdditionalUpdateRecipes(rewriteAdditionalUpdateRecipes);
        }
        if (rewritePluginVersion != null) {
            invoker.rewritePluginVersion(rewritePluginVersion);
        }
        invoker.targetPlatformVersion(targetPlatformVersion);
        invoker.rewriteDryRun(rewriteDryRun);

        // backward compat

View on GitHub (pinned to e1c734241f)

Solutions

Check network connectivity to the configured registry (curl the registry URL from the same machine).
Fix quarkus registry configuration (quarkus.registries in ~/.quarkus/config.yaml or project config).
Clear the local registry cache (~/.quarkus/registry) and retry.
Configure proxy settings (HTTPS_PROXY / registry client proxy config) if behind a corporate proxy.
Verify the io.quarkus.registry:quarkus-registry-client version matches the Quarkus version in use.

Defensive patterns

Strategy: retry

Validate before calling

curl -fsS https://registry.quarkus.io/ >/dev/null && echo registry reachable
# and verify registry config:
cat ~/.quarkus/config.yaml 2>/dev/null | grep -A3 registries

Try / catch

try {
    ./gradlew quarkusUpdate
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to resolve the recommended Quarkus extension catalog")) {
        // check network/proxy, clear ~/.quarkus/registry cache, retry
    }
}

Prevention

Verify registry connectivity/proxy settings before running update tasks in CI
Keep the quarkus-registry-client version in sync with your Quarkus version
Periodically clear the local registry cache (~/.quarkus/registry)
Configure registry mirrors for air-gapped environments

When it happens

Trigger: Running ./gradlew quarkusUpdate when the configured registries are unreachable (no network, proxy/firewall blocking), a registry URL in quarkus.registries is wrong, the registry returns HTTP errors (4xx/5xx), or the local registry cache is corrupt.

Common situations: Corporate proxy blocking registry.quarkus.io; offline/air-gapped environment; typos in io.quarkus.registry.quarkus-registry-descriptor config; registry service outage; stale io.quarkus.registry client version incompatible with the registry response.

Related errors

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