quarkusio/quarkus · error · UncheckedIOException

Failed to deserialize extension metadata from ${url}

Error message

Failed to deserialize extension metadata from ${url}

What it means

When building a TopExtensionDependency without pre-supplied catalog metadata, the devtools read the extension's quarkus-extension.json descriptor from the resolved artifact's content tree and deserialize it into an Extension. This UncheckedIOException is thrown when reading or parsing that descriptor file fails via Extension.fromFile(), with the offending descriptor URL in the message.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/devtools/project/state/TopExtensionDependency.java:55

        public Builder setCatalogMetadata(Extension metadata) {
            this.catalogMetadata = metadata;
            return this;
        }

        public Builder setTransitive(boolean transitive) {
            this.transitive = transitive;
            return this;
        }

        public TopExtensionDependency build() {
            if (catalogMetadata == null) {
                catalogMetadata = ExtensionMetadataUtil.applyExtensionMetadata(
                        resolvedDep.getContentTree(), visit -> {
                            try {
                                return Extension.fromFile(visit.getPath());
                            } catch (IOException e) {
                                throw new UncheckedIOException(
                                        "Failed to deserialize extension metadata from " + visit.getUrl(), e);
                            }
                        });
            }
            return new TopExtensionDependency(coords, catalogMetadata, ExtensionProvider.key(getOrigin(catalogMetadata)),
                    transitive);
        }

        public ArtifactKey getKey() {
            return resolvedDep == null ? null : resolvedDep.getKey();
        }

        private static ExtensionOrigin getOrigin(Extension metadata) {
            if (metadata == null || metadata.getOrigins().isEmpty()) {
                return null;
            }
            ExtensionOrigin origin = metadata.getOrigins().get(0);
            if (origin.isPlatform()) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Delete the corrupted artifact directory from the local Maven repository (~/.m2/repository/<group>/<artifact>/<version>) and re-resolve/rebuild
2. Check the URL in the message; open the quarkus-extension.json it points to and verify it is valid JSON
3. Verify the dependency is a real Quarkus extension jar containing META-INF/quarkus-extension/quarkus-extension.json
4. Provide catalogMetadata explicitly via Builder.setCatalogMetadata() so the file-descriptor path is skipped

Example fix

# before (corrupt cached artifact)
mvn quarkus:update
# after: purge the corrupt artifact then retry
rm -rf ~/.m2/repository/io/quarkus/ext/acme/1.0.0
mvn -U quarkus:update

// before building the dependency
try (var is = Files.newInputStream(visit.getPath())) {
    new String(is.readAllBytes(), StandardCharsets.UTF_8).contains("\"dependencies\""); // sanity: JSON present
}

try {
    TopExtensionDependency dep = TopExtensionDependency.builder()
        .setResolvedDependency(resolvedDep).build();
} catch (UncheckedIOException e) {
    log.error("Corrupt extension descriptor at " + e.getMessage() + ": " + e.getCause());
    // purge the artifact from local repo and re-resolve
}

When it happens

Trigger: Calling TopExtensionDependency.Builder.build() when resolvedDep has no catalogMetadata and the quarkus-extension.json inside the artifact's content tree is missing, truncated, corrupted (e.g. partial download of a jar into the local Maven repository), or unreadable.

Common situations: Interrupted Maven downloads leaving corrupt jars in ~/.m2/repository, custom/snapshot artifacts built without the quarkus-extension descriptor, wrong classifier/type on a dependency so the wrong content tree is read, file permission problems in the local repo.

Related errors

• Unexpected end of stream while reading application config fi
• Failed to deserialize registries descriptor ${file}
• Failed to open path tree with root %s
• Failed to read %s
• Failed to read resources from classpath

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