quarkusio/quarkus · error · RegistryResolutionException

Failed to parse Quarkus extension catalog ${jsonPath}

Error message

Failed to parse Quarkus extension catalog ${jsonPath}

What it means

This error is thrown by MavenPlatformExtensionsResolver.resolvePlatformExtensions when the downloaded Quarkus extension catalog JSON file could not be read or parsed. The resolver fetched the catalog artifact for a platform BOM, then ExtensionCatalog.mutableFromFile(jsonPath) failed with an IOException while opening or deserializing the JSON. The original IOException is preserved as the cause.

Source

Thrown at independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/client/maven/MavenPlatformExtensionsResolver.java:81

            if (repo != null) {
                buf.append(" from Maven repository ").append(repo.getId()).append(" (").append(repo.getUrl()).append(")");
                final List<RemoteRepository> mirrored = repo.getMirroredRepositories();
                if (!mirrored.isEmpty()) {
                    buf.append(" which is a mirror of ");
                    buf.append(mirrored.get(0).getId()).append(" (").append(mirrored.get(0).getUrl()).append(")");
                    for (int i = 1; i < mirrored.size(); ++i) {
                        buf.append(", ").append(mirrored.get(i).getId()).append(" (").append(mirrored.get(i).getUrl())
                                .append(")");
                    }
                    buf.append(". The mirror may be out of sync.");
                }
            }
            throw new RegistryResolutionException(buf.toString(), e);
        }
        try {
            return ExtensionCatalog.mutableFromFile(jsonPath);
        } catch (IOException e) {
            throw new RegistryResolutionException("Failed to parse Quarkus extension catalog " + jsonPath, e);
        }
    }

    private String resolveLatestBomVersion(ArtifactCoords bom, String versionRange)
            throws RegistryResolutionException {
        final Artifact bomArtifact = new DefaultArtifact(bom.getGroupId(),
                PlatformArtifacts.ensureBomArtifactId(bom.getArtifactId()),
                "", "pom", bom.getVersion());
        log.debug("Resolving the latest version of %s:%s:%s:%s in the range %s", bom.getGroupId(), bom.getArtifactId(),
                bom.getClassifier(), bom.getType(), versionRange);
        try {
            return artifactResolver.getLatestVersionFromRange(bomArtifact, versionRange);
        } catch (Exception e) {
            throw new RegistryResolutionException("Failed to resolve the latest version of " + bomArtifact.getGroupId()
                    + ":" + bom.getArtifactId() + ":" + bom.getClassifier() + ":" + bom.getType() + ":" + versionRange, e);
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Delete the stale catalog file from the local Maven repository (e.g. rm -rf ~/.m2/repository/io/quarkus/platform/<g>/<a>/<v>) and retry, forcing re-download.
2. Verify the file at the path printed in the message is valid JSON (jq . <path>) and not an HTML error page; fix the proxy/mirror if it is.
3. Run with a clean local repo (mvn -U or -Dmaven.repo.local=<fresh-dir>) to rule out cache corruption.
4. Confirm the Quarkus platform/registry versions match between project config and the registry client; mismatched JSON schema versions can fail parsing.
5. Check file permissions on the local repository directory.

Example fix

// before: relying on a possibly corrupted shared cache
mvn quarkus:update -DplatformArtifact=io.quarkus.platform:quarkus-bom:2.16.0
// after: force fresh resolution with a clean local repo
mvn -Dmaven.repo.local=/tmp/clean-m2 quarkus:update -DplatformArtifact=io.quarkus.platform:quarkus-bom:2.16.0

Path jsonPath = Path.of("...catalog.json");
// pre-check: file exists, readable, non-empty, and looks like JSON
if (!Files.isReadable(jsonPath) || Files.size(jsonPath) == 0) {
    throw new IllegalStateException("Catalog file missing/empty: " + jsonPath);
}
try (var parser = Json.createParser(Files.newBufferedReader(jsonPath))) {
    while (parser.hasNext()) parser.next(); // throws if malformed
}

static boolean isReadableJsonFile(Path p) {
    try {
        return Files.isRegularFile(p) && Files.isReadable(p)
            && Files.size(p) > 0
            && p.getFileName().toString().endsWith(".json");
    } catch (IOException e) { return false; }
}

try {
    catalog = resolver.resolvePlatformExtensions(bom, quarkusVersion);
} catch (RegistryResolutionException e) {
    if (e.getMessage().startsWith("Failed to parse Quarkus extension catalog")) {
        // corrupt catalog: purge cached file and retry once
        Files.deleteIfExists(Path.of(e.getMessage().replace("Failed to parse Quarkus extension catalog ", "")));
        catalog = resolver.resolvePlatformExtensions(bom, quarkusVersion);
    } else throw e;
}

When it happens

Trigger: Calling resolvePlatformExtensions with a platform BOM whose extension-catalog JSON artifact exists on disk but is corrupted, truncated, partially downloaded, empty, or not valid Quarkus extension-catalog JSON; also when jsonPath points to a file that cannot be opened (permissions, deleted mid-run).

Common situations: A corrupted local Maven repository cache (~/.m2/repository) after an interrupted download; a mirror or corporate proxy serving an HTML error page saved as the catalog JSON; an extension catalog produced by an incompatible Quarkus registry/JSON schema version; read-permission problems in a shared CI cache.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to load platform catalog from ${jsonFile}
• Failed to resolve Quarkus extension catalog
• Failed to resolve the extension catalog for stream '${stream
• Failed to resolve the available updates
• Failed to list extension categories

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