quarkusio/quarkus · error · RuntimeException

Failed to resolve extension catalog

Error message

Failed to resolve extension catalog

What it means

QuarkusPlatformTask.extensionsCatalog resolves the extension catalog via an ExtensionCatalogResolver when registries are configured and the task is not limited to imported platforms. If catalog resolution throws, it wraps the cause in a RuntimeException 'Failed to resolve extension catalog'. When no registries exist, it falls back to merging platforms from the app model resolver.

Source

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

    // Captured at configuration time so the task actions do not call Task.getProject() at execution time, which is
    // deprecated and removed in Gradle 10. The platform tasks are not compatible with the configuration cache, so
    // holding a Project reference is acceptable (it is never serialized).
    private final transient Project project;

    QuarkusPlatformTask(String description) {
        super(description);
        this.project = getProject();
    }

    private ExtensionCatalog extensionsCatalog(boolean limitExtensionsToImportedPlatforms, MessageWriter log) {
        final List<ArtifactCoords> platforms = importedPlatforms();
        ExtensionCatalogResolver catalogResolver;
        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;
    }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Inspect the cause chain with --stacktrace to identify the registry failure.
  2. Verify registry connectivity: curl https://registry.quarkus.io and configure proxy/TLS settings if needed.
  3. Confirm requested platform coordinates (groupId:artifactId:version) exist in the registry.
  4. Restrict the task to imported platforms (quarkus.limitExtensionsToImportedPlatforms equivalent) to use the local model instead of registries.
  5. Declare the platform in the build so the ToolsUtils.mergePlatforms fallback path can resolve it without a registry.

Example fix

// before: request unknown platform
./gradlew addExtension --extensions=rest --platform=io.quarkus.platform:quarkus-bom:0.0
// after: use a valid platform or rely on the imported one
./gradlew addExtension --extensions=rest
Defensive patterns

Strategy: fallback

Validate before calling

// Resolve catalog dependencies up front; fall back to imported-platforms mode on failure
./gradlew dependencyInsight --dependency quarkus-bom  # platform must resolve locally
curl -fsSL https://registry.quarkus.io/ > /dev/null || echo "fall back to imported platforms"

Try / catch

try {
  ./gradlew addExtension --extensions=rest
} catch (RuntimeException e) {
  if (e.getMessage().equals("Failed to resolve extension catalog")) {
    // inspect cause with --stacktrace; ensure the platform is declared so the
    // local mergePlatforms fallback can be used, or fix registry access
  }
}

Prevention

When it happens

Trigger: Running platform-dependent Quarkus Gradle tasks (e.g. addExtension, listExtensions) where catalogResolver.resolveExtensionCatalog(platforms) throws — registry unreachable, unknown platform coordinates, or catalog format errors; raised in extensionsCatalog, called by catalog.

Common situations: Network outages or proxy/firewall blocks to registry.quarkus.io; specifying a platform version that does not exist; registry misconfiguration; TLS certificate issues in corporate environments.

Related errors

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