quarkusio/quarkus · error · RuntimeException

Failed to resolve the Quarkus extension catalog

Error message

Failed to resolve the Quarkus extension catalog

What it means

Also in QuarkusProjectHelper.getCachedProject: after the build tool is known, resolveExtensionCatalog() fetches the Quarkus extension catalog. Any exception during resolution (network, malformed descriptor, parsing) is wrapped as RuntimeException 'Failed to resolve the Quarkus extension catalog', and the cached project is not created.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/devtools/project/QuarkusProjectHelper.java:68

        if (cachedProject == null) {
            PrintStream nullPrintStream = new PrintStream(OutputStream.nullOutputStream());
            log = MessageWriter.info(nullPrintStream);
            BuildTool buildTool = detectExistingBuildTool(projectDir);
            if (buildTool == null) {
                buildTool = BuildTool.MAVEN;
            }
            if (BuildTool.MAVEN.equals(buildTool)) {
                try {
                    return MavenProjectBuildFile.getProject(projectDir, log, null);
                } catch (RegistryResolutionException e) {
                    throw new RuntimeException("Failed to initialize the Quarkus Maven extension manager", e);
                }
            }
            final ExtensionCatalog catalog;
            try {
                catalog = resolveExtensionCatalog();
            } catch (Exception e) {
                throw new RuntimeException("Failed to resolve the Quarkus extension catalog", e);
            }
            cachedProject = getProject(projectDir, catalog, buildTool, JavaVersion.NA, log);
        }

        return cachedProject;
    }

    public static QuarkusProject getProject(Path projectDir) {
        BuildTool buildTool = detectExistingBuildTool(projectDir);
        if (buildTool == null) {
            buildTool = BuildTool.MAVEN;
        }
        return getProject(projectDir, buildTool);
    }

    @Deprecated
    public static QuarkusProject getProject(Path projectDir, String quarkusVersion) {
        // TODO remove this method once the default registry becomes available

View on GitHub (pinned to e1c734241f)

Solutions

  1. Restore connectivity to the Quarkus registry or configure a reachable mirror via quarkus.registry.
  2. Clear the local registry cache so a fresh descriptor is downloaded.
  3. Check that the registry returns a valid JSON descriptor (curl it and validate).
  4. Work offline with a pre-seeded local registry cache.
Defensive patterns

Strategy: fallback

Validate before calling

// Validate the registry descriptor resolves and parses before use
HttpResponse<String> resp = client.send(HttpRequest.newBuilder(URI.create(registryUrl)).GET().build(), HttpResponse.BodyHandlers.ofString());
if (resp.statusCode() != 200 || !resp.body().trim().startsWith("{")) {
    throw new IllegalStateException("Invalid registry descriptor from " + registryUrl);
}

Try / catch

try {
    project = QuarkusProjectHelper.getCachedProject(projectDir, log);
} catch (RuntimeException e) {
    if ("Failed to resolve the Quarkus extension catalog".equals(e.getMessage())) {
        // fall back to a cached catalog or mirror URL, then retry
    } else throw e;
}

Prevention

When it happens

Trigger: getCachedProject reaching resolveExtensionCatalog() on a non-Maven (or fallback) path where the catalog request throws — DNS failure, HTTP error, invalid JSON registry descriptor.

Common situations: Gradle projects built offline; proxy/firewall blocking registry.quarkus.io; corrupt cached registry metadata; a registry returning an unexpected/incompatible descriptor format.

Related errors

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