quarkusio/quarkus · error · RuntimeException

Failed to resolve platform descriptor ${platform}

Error message

Failed to resolve platform descriptor ${platform}

What it means

Thrown by ToolsUtils.mergePlatforms when the Maven artifact resolver cannot resolve one of the platform descriptor coordinates passed to it. The wrapping RuntimeException carries the ArtifactCoords of the platform that failed, with the underlying resolver exception as the cause.

Source

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

        return catalog;
    }

    public static ExtensionCatalog mergePlatforms(List<ArtifactCoords> platforms, MavenArtifactResolver artifactResolver) {
        // TODO remove this method once we have the registry service available
        return mergePlatforms(platforms, new BootstrapAppModelResolver(artifactResolver));
    }

    public static ExtensionCatalog mergePlatforms(List<ArtifactCoords> platforms, AppModelResolver artifactResolver) {
        // TODO remove this method once we have the registry service available
        List<ExtensionCatalog> catalogs = new ArrayList<>(platforms.size());
        for (ArtifactCoords platform : platforms) {
            final Path json;
            try {
                json = artifactResolver.resolve(ArtifactCoords.of(platform.getGroupId(), platform.getArtifactId(),
                        platform.getClassifier(), platform.getType(), platform.getVersion())).getResolvedPaths()
                        .getSinglePath();
            } catch (Exception e) {
                throw new RuntimeException("Failed to resolve platform descriptor " + platform, e);
            }
            try {
                catalogs.add(ExtensionCatalog.fromFile(json));
            } catch (IOException e) {
                throw new RuntimeException("Failed to deserialize platform descriptor " + json, e);
            }
        }
        return CatalogMergeUtility.merge(catalogs);
    }

    @SuppressWarnings("unchecked")
    public static Properties readQuarkusProperties(ExtensionCatalog catalog) {
        Map<Object, Object> map = (Map<Object, Object>) catalog.getMetadata().getOrDefault("project", Collections.emptyMap());
        map = (Map<Object, Object>) map.getOrDefault("properties", Collections.emptyMap());
        final Properties properties = new Properties();
        map.entrySet().forEach(
                e -> properties.setProperty(e.getKey().toString(), e.getValue() == null ? null : e.getValue().toString()));
        return properties;

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the coordinates of the failing platform (printed in the message) against the repository listing
2. Ensure all repositories hosting the imported platforms are configured
3. Validate the version exists (mvn dependency:get) before merging
4. Fix network/proxy issues indicated by the root cause

Example fix

// before
mergePlatforms(List.of(ArtifactCoords.of("io.quarkus.platform","quarkus-bom",null,"json","3.0.0.Final"),
                       ArtifactCoords.of("io.quarkiverse.foo","quarkus-foo-bom",null,"json","0.0.1")))
// after: use a released bom version
mergePlatforms(List.of(ArtifactCoords.of("io.quarkus.platform","quarkus-bom",null,"json","3.15.1"),
                       ArtifactCoords.of("io.quarkiverse.foo","quarkus-foo-bom",null,"json","2.0.0")))

for (ArtifactCoords p : platforms) {
    // pre-flight: ensure coordinates are complete and version non-empty
    if (p.getVersion() == null || p.getVersion().isBlank())
        throw new IllegalArgumentException("Missing version for platform " + p);
}

try {
    mergePlatforms(platforms);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to resolve platform descriptor")) {
        // log e.getCause() to distinguish 404 vs network vs auth
    }
    throw e;
}

When it happens

Trigger: Calling mergePlatforms with a platform entry (groupId/artifactId/classifier/type/version) that cannot be downloaded: nonexistent version, missing repository, or network failure during artifactResolver.resolve(...).

Common situations: Merging imported platforms where one member platform version does not exist; restricted corporate repositories; typo in a platform coordinate in a config.

Related errors

• Failed to resolve extension catalog for ${coords}. Make sure
• 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/f0e68a7c40fc9f44. Report an issue: GitHub.