quarkusio/quarkus · error · RuntimeException

Failed to initialize Quarkus extension catalog resolver

Error message

Failed to initialize Quarkus extension catalog resolver

What it means

QuarkusPlatformTask.getExtensionCatalogResolver lazily builds an ExtensionCatalogResolver for resolving the platform registry catalog. If QuarkusProjectHelper.getCatalogResolver(log) throws a RegistryResolutionException (e.g. it cannot contact or parse the configured registries), the task wraps it in a RuntimeException with this message. It signals the platform/registry configuration could not be used to initialize extension resolution.

Source

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

        catalogResolver = getExtensionCatalogResolver(log);
        if (catalogResolver.hasRegistries() && !limitExtensionsToImportedPlatforms) {
            try {
                return catalogResolver.resolveExtensionCatalog(platforms);
            } catch (Exception e) {
                throw new RuntimeException("Failed to resolve extension catalog", e);
            }
        }
        return ToolsUtils.mergePlatforms(platforms, extension().getAppModelResolver());
    }

    protected ExtensionCatalogResolver getExtensionCatalogResolver(MessageWriter log) {
        if (catalogResolver == null) {
            try {
                catalogResolver = QuarkusProjectHelper.isRegistryClientEnabled()
                        ? QuarkusProjectHelper.getCatalogResolver(log)
                        : ExtensionCatalogResolver.empty();
            } catch (RegistryResolutionException e) {
                throw new RuntimeException("Failed to initialize Quarkus extension catalog resolver", e);
            }
        }
        return catalogResolver;
    }

    protected List<ArtifactCoords> importedPlatforms() {
        final List<Dependency> bomDeps = listProjectBoms(project);
        if (bomDeps.isEmpty()) {
            throw new GradleException("No platforms detected in the project");
        }

        final Configuration boms = project.getConfigurations()
                .detachedConfiguration(bomDeps.toArray(new org.gradle.api.artifacts.Dependency[0]));
        final Set<ArtifactKey> processedKeys = new HashSet<>(1);

        List<ArtifactCoords> platforms = new ArrayList<>();
        boms.getResolutionStrategy().eachDependency(d -> {
            if (!d.getTarget().getName().endsWith(BootstrapConstants.PLATFORM_DESCRIPTOR_ARTIFACT_ID_SUFFIX)

View on GitHub (pinned to e1c734241f)

Solutions

Fix quarkus.registry endpoints in gradle.properties / application.properties so the URLs are reachable (test with curl).
Check network/proxy/SSL settings (HTTPS_PROXY, truststore) and retry; disable the registry client via quarkus.registry.enabled=false if not needed.
Clear stale registry cache under ~/.quarkus/ (e.g. broken cached catalogs) and rerun the task.

Example fix

// before (gradle.properties)
quarkus.registry=https://bad-registry.example.com

// after
quarkus.registry=https://registry.quarkus.io

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check registry reachability before running the task
def endpoint = 'https://registry.quarkus.io'
try { new URL(endpoint).openConnection().connectTimeout = 5000 }.collect { } // throws if malformed/unreachable

Try / catch

try { ./gradlew listExtensions } catch (RuntimeException e) { if (e.message.contains('Failed to initialize Quarkus extension catalog resolver')) { /* fix registry config or disable registry client */ } }

Prevention

Keep quarkus.registry endpoints reachable; test with curl in CI before builds.
Set quarkus.registry.enabled=false for offline builds if no custom registry is needed.
Clear ~/.quarkus cache when registry responses look stale or corrupt.

When it happens

Trigger: Running a Quarkus Gradle platform task (e.g. quarkusPlatformTasks like listExtensions/addExtension) when quarkus.registry.* points to an unreachable or invalid registry, network access fails, or the registry client returns an unparseable/invalid catalog response.

Common situations: Corporate proxy/firewall blocking registry.quarkus.io; mistyped quarkus.registry URL; offline CI builds; SSL certificate issues; broken custom registry configuration in gradle.properties or application config.

Related errors

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