quarkusio/quarkus · error · RuntimeException

Failed to resolve extension catalog for ${coords}. Make sure

Error message

Failed to resolve extension catalog for ${coords}. Make sure the groupId, artifactId and version are spelled correctly and the relevant Maven repositories are configured.

What it means

Thrown by ToolsUtils.resolvePlatformDescriptorDirectly when the Maven artifact resolver cannot download the platform BOM (converted to a JSON extension catalog artifact) for the requested coordinates. It wraps the underlying resolver exception and indicates the coordinates or repository configuration are wrong. The message includes the compact BOM coordinates so the offending artifact is identifiable.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/tools/ToolsUtils.java:157

                catalogCoords = new DefaultArtifact(
                        ToolsConstants.IO_QUARKUS,
                        "quarkus-bom" + BootstrapConstants.PLATFORM_DESCRIPTOR_ARTIFACT_ID_SUFFIX,
                        catalogCoords.getClassifier(), catalogCoords.getExtension(), catalogCoords.getVersion());
                try {
                    log.debug("Resolving platform descriptor %s", catalogCoords);
                    platformJson = artifactResolver.resolve(catalogCoords).getArtifact().getFile().toPath();
                } catch (Exception e2) {
                }
            }
            if (platformJson == null) {
                final StringBuilder sb = new StringBuilder();
                sb.append("Failed to resolve extension catalog for ");
                sb.append(PlatformArtifacts.ensureBomArtifact(ArtifactCoords.of(catalogCoords.getGroupId(),
                        catalogCoords.getArtifactId(), catalogCoords.getClassifier(), catalogCoords.getExtension(),
                        catalogCoords.getVersion())).toCompactCoords());
                sb.append(
                        ". Make sure the groupId, artifactId and version are spelled correctly and the relevant Maven repositories are configured.");
                throw new RuntimeException(sb.toString(), e);
            }
        }
        ExtensionCatalog catalog;
        try {
            catalog = ExtensionCatalog.fromFile(platformJson);
        } catch (IOException e) {
            throw new RuntimeException("Failed to deserialize extension catalog " + platformJson, e);
        }
        Map<String, Object> md = catalog.getMetadata();
        if (md != null) {
            Object o = md.get("platform-release");
            if (o instanceof Map) {
                Object members = ((Map<?, ?>) o).get("members");
                if (members instanceof Collection) {
                    final Collection<?> memberList = (Collection<?>) members;
                    final List<ExtensionCatalog> catalogs = new ArrayList<>(memberList.size());

                    int memberIndex = 0;

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the groupId, artifactId and version of the platform BOM (e.g. io.quarkus.platform:quarkus-bom:<version>) match a published release
2. Add the repository hosting the platform artifacts (e.g. Maven Central or the Quarkus snapshots repo) to settings.xml or the project POM
3. Run mvn dependency:get -Dartifact=<coords> to reproduce and see the detailed underlying resolution error
4. Check the underlying 'caused by' exception for 401/403 (auth) vs 404 (missing artifact) to pinpoint the issue

Example fix

// before: resolvePlatformDescriptorDirectly("io.quarkus.platform:quarkus-bom:999-SNAPSHOT")
// after: use an existing version
resolvePlatformDescriptorDirectly("io.quarkus.platform:quarkus-bom:3.15.1")

// Validate coordinates and repository access before resolving
String coords = groupId + ":" + artifactId + ":" + version;
Process p = new ProcessBuilder("mvn", "dependency:get", "-Dartifact=" + coords).inheritIO().start();
if (p.waitFor() != 0) throw new IllegalStateException("Artifact not resolvable: " + coords);

try {
    resolvePlatformDescriptorDirectly(coords);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to resolve extension catalog")) {
        // inspect cause: 404 => bad coords, 401/403 => auth, UnknownHost => network
    }
    throw e;
}

When it happens

Trigger: Calling resolvePlatformDescriptorDirectly with catalog coordinates whose groupId/artifactId/version do not exist in any configured repository, or when the required Maven repository is not configured in settings.xml/pom.

Common situations: Typos in the quarkus platform BOM coordinates; pinning a Quarkus version that was never released; corporate Nexus/Artifactory mirror missing the quarkus repo; offline environment without cached artifacts.

Related errors

• Failed to resolve platform descriptor ${platform}
• The 'stream' parameter cannot be combined with 'platformGrou
• Failed to resolve artifact ${artifact}
• Failed to resolve
• Failed to resolve artifact ${artifact}

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