quarkusio/quarkus · error · MojoExecutionException

Failed to resolve the extension catalog for stream '${stream

Error message

Failed to resolve the extension catalog for stream '${stream}'

What it means

After successfully parsing the stream coordinates, resolveExtensionsCatalogForStream calls catalogResolver.resolveExtensionCatalog(streamCoords); a RegistryResolutionException there is rethrown as this MojoExecutionException. It means the registry client could not fetch the extension catalog metadata for the requested stream — the input was valid, but metadata resolution failed.

Source

Thrown at devtools/maven/src/main/java/io/quarkus/maven/CreateProjectMojo.java:427

            ExtensionCatalogResolver catalogResolver) throws MojoExecutionException {
        if (!catalogResolver.hasRegistries()) {
            throw new MojoExecutionException(
                    "Specifying a stream requires the Quarkus extension registry client."
                            + " Please make sure the registry client is enabled.");
        }
        final PlatformStreamCoords streamCoords;
        try {
            streamCoords = PlatformStreamCoords.fromString(stream.trim());
        } catch (IllegalArgumentException e) {
            throw new MojoExecutionException(
                    "Invalid stream value '" + stream + "'."
                            + " Value should be specified as 'platformKey:streamId', for example: 3.15 or io.quarkus.platform:3.15",
                    e);
        }
        try {
            return catalogResolver.resolveExtensionCatalog(streamCoords);
        } catch (RegistryResolutionException e) {
            throw new MojoExecutionException("Failed to resolve the extension catalog for stream '" + stream + "'", e);
        }
    }

    private static ExtensionCatalog resolveExtensionCatalogDirectly(AbstractMojo mojo, String groupId, String artifactId,
            String version,
            ExtensionCatalogResolver catalogResolver, MavenArtifactResolver artifactResolver, MessageWriter log) {
        groupId = getPlatformGroupId(mojo, groupId);
        artifactId = getPlatformArtifactId(artifactId);
        version = getPlatformVersion(mojo, version);
        final ExtensionCatalog catalog = ToolsUtils.resolvePlatformDescriptorDirectly(groupId, artifactId, version,
                artifactResolver, log);

        final StringBuilder buf = new StringBuilder();
        buf.append("The extension catalog will be narrowed to the ").append(groupId).append(":").append(artifactId)
                .append(":").append(version).append(" platform release.");
        if (!QuarkusProjectHelper.isRegistryClientEnabled()) {
            buf.append(
                    " To enable the complete Quarkiverse extension catalog along with the latest recommended platform releases, please, make sure the extension registry client is enabled.");

View on GitHub (pinned to e1c734241f)

Solutions

Inspect the 'Caused by' RegistryResolutionException for the exact resolution failure
Verify network access to the configured Quarkus registry (https://registry.quarkus.io) or your mirror
Confirm the stream actually exists (check code.quarkus.io or registry metadata) — e.g. 3.15 not 3.99
Refresh cached registry data: remove io/quarkus/registry artifacts from ~/.m2/repository and retry
Fall back to explicit platform coordinates (platformGroupId/platformArtifactId/platformVersion) resolved from Maven Central instead of the registry

Example fix

# before: stream that the registry cannot resolve
mvn quarkus:create -Dstream=3.99
# after: pin a real published version via coordinates
mvn quarkus:create -DplatformGroupId=io.quarkus.platform -DplatformArtifactId=quarkus-bom -DplatformVersion=3.15.1

Defensive patterns

Strategy: retry

Validate before calling

# Pre-check reachability of the registry
curl -fsSL https://registry.quarkus.io/maven/io/quarkus/registry/quarkus-registry.json -o /dev/null && echo OK
# And confirm the stream exists in that metadata

Try / catch

// Retry transient resolution failures, then fall back to Maven-coordinate resolution
try { return resolver.resolveExtensionCatalog(streamCoords); }
catch (RegistryResolutionException e) {
    if (isTransient(e)) return retry(streamCoords);
    return resolveViaMavenCoordinates(platformGav); // fallback
}

Prevention

Verify the stream exists before using it (check registry metadata or code.quarkus.io)
Allow registry.quarkus.io through proxies/firewalls
Clear stale ~/.m2 registry metadata after long-lived offline periods
Keep an explicit platformVersion fallback documented for CI

When it happens

Trigger: Running create/add-extension with -Dstream=<valid stream> when the registry server is unreachable, the registry quarkus-registry.json is missing or malformed, Maven repository resolution of the registry artifact fails, or the requested stream does not exist in the registry.

Common situations: Corporate proxies/firewalls blocking registry.quarkus.io; stale cached registry metadata in ~/.m2; specifying a stream (e.g. 99.0) the registry has never published; transient server outages.

Related errors

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