quarkusio/quarkus · error · IllegalStateException

Failed to parse Quarkus extension metadata ${path}

Error message

Failed to parse Quarkus extension metadata ${path}

What it means

After the extension jar is resolved, completeCatalog reads its embedded Quarkus extension metadata (quarkus-extension.yaml). If reading that file throws an IOException, the metadata visitor throws this IllegalStateException, meaning the artifact exists but its Quarkus extension metadata could not be parsed/read.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/devtools/commands/CreateProjectHelper.java:85

    public static ExtensionCatalog completeCatalog(ExtensionCatalog catalog, Collection<String> extensions,
            MavenArtifactResolver mvn) {
        ExtensionCatalog.Mutable mutableCatalog = null;
        for (String extArg : extensions) {
            if (isFullArtifactCoords(extArg)) {
                var coords = ArtifactCoords.fromString(extArg.trim());
                final Path extJar;
                try {
                    extJar = mvn.resolve(new DefaultArtifact(coords.getGroupId(), coords.getArtifactId(),
                            coords.getClassifier(), coords.getType(), coords.getVersion())).getArtifact().getFile().toPath();
                } catch (BootstrapMavenException e) {
                    throw new RuntimeException("Failed to resolve extension " + coords, e);
                }
                final Extension ext = ExtensionMetadataUtil.applyExtensionMetadata(
                        PathTree.ofDirectoryOrArchive(extJar), visit -> {
                            try {
                                return Extension.fromFile(visit.getPath());
                            } catch (IOException e) {
                                throw new IllegalStateException(
                                        "Failed to parse Quarkus extension metadata " + visit.getPath());
                            }
                        });
                if (ext != null) {
                    if (mutableCatalog == null) {
                        mutableCatalog = catalog.mutable();
                    }
                    var i = mutableCatalog.getExtensions().iterator();
                    boolean add = true;
                    while (i.hasNext()) {
                        final ArtifactCoords catalogCoords = i.next().getArtifact();
                        if (catalogCoords.getKey().equals(ext.getArtifact().getKey())) {
                            if (catalogCoords.getVersion().equals(ext.getArtifact().getVersion())) {
                                add = false;
                            } else {
                                i.remove();
                            }
                            break;

View on GitHub (pinned to e1c734241f)

Solutions

1. Delete the corrupted artifact from the local Maven repository and re-resolve it
2. Verify the jar contains META-INF/quarkus-extension.yaml and is a valid zip
3. Check file permissions on the local repository path
4. Confirm the artifact was actually built/published as a Quarkus extension

Example fix

// clear corrupted cached artifact
rm -rf ~/.m2/repository/com/acme/acme-extension/1.0.0
// then re-run the create project command to re-download

Path jar = resolvedJar;
try (var fs = new java.util.zip.ZipFile(jar.toFile())) { if (fs.getEntry("META-INF/quarkus-extension.yaml") == null) throw new IllegalStateException("not a quarkus extension jar"); }

try { helper.completeCatalog(...); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Failed to parse Quarkus extension metadata")) { deleteAndReDownloadArtifact(); } }

When it happens

Trigger: completeCatalog applying extension metadata to a resolved jar via ExtensionMetadataUtil when Extension.fromFile throws IOException on the metadata path (corrupt jar, unreadable archive entry, malformed file entry).

Common situations: Corrupted or partially downloaded jar in the local Maven repository; jar not being a valid Quarkus extension archive; filesystem permission problems reading the extracted entry.

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 process
• Failed to read
• Unable to read entry: ${fileEntry.getName()} from jar: ${jar
• Unable to read entry: ${configFileName} from jar: ${jarFile}
• Failed to open ${jarResource.jarPath}

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