quarkusio/quarkus · error · IOException

Invalid quarkus-extension.yaml metadata: <schema validation

Error message

Invalid quarkus-extension.yaml metadata: <schema validation errors>

What it means

validate checks an extension descriptor object against the JSON Schema (draft 2020-12). When schema validation fails, all errors are collected into a single IOException whose message lists each instance location and message, prefixed 'Invalid quarkus-extension.yaml metadata:'.

Source

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

            if (is == null) {
                throw new IOException(
                        "Failed to load extension metadata schema from " + ToolsConstants.EXTENSION_SCHEMA_RESOURCE);
            }

            final SchemaRegistry schemaRegistry = SchemaRegistry.withDefaultDialect(SpecificationVersion.DRAFT_2020_12);
            schema = schemaRegistry.getSchema(is, InputFormat.JSON);
            schema.initializeValidators();
        }

        final List<com.networknt.schema.Error> errors = schema.validate(extObject.toString(), InputFormat.JSON);
        if (!errors.isEmpty()) {
            final StringBuilder sb = new StringBuilder();
            sb.append("Invalid ").append(BootstrapConstants.QUARKUS_EXTENSION_FILE_NAME).append(" metadata:");
            for (com.networknt.schema.Error err : errors) {
                sb.append(System.lineSeparator()).append("- ").append(err.getInstanceLocation()).append(": ")
                        .append(err.getMessage());
            }
            throw new IOException(sb.toString());
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Read each '- <location>: <message>' line in the error to identify the offending fields and fix the quarkus-extension.yaml accordingly
2. Regenerate the descriptor with the current Quarkus extension tooling (quarkus-maven-plugin extension goals) instead of hand-editing
3. Compare the descriptor against the schema resource shipped with your Quarkus version to see required fields

Example fix

// before
name: ""            # empty name fails schema
artifact: "my-ext"  # missing group/version
// after
name: "My Extension"
description: "An example extension"
artifact: "com.example:my-ext::jar:1.0.0"

// pre-check the essential required fields before validation
if (extObject.path("group-id").isMissingNode() || extObject.path("artifact-id").isMissingNode()
        || extObject.path("version").isMissingNode()) {
    throw new IllegalArgumentException("Descriptor missing group-id/artifact-id/version");
}
ExtensionMetadataValidator.validate(extObject);

try {
    ExtensionMetadataValidator.validate(extObject);
} catch (IOException e) {
    if (e.getMessage().startsWith("Invalid quarkus-extension.yaml")) {
        // e.getMessage() lists '- <location>: <message>' per error; log or surface them
        throw new IllegalArgumentException("Fix descriptor fields listed in: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: Calling validate(ObjectNode) with a descriptor whose content violates the schema: missing required fields (group-id/artifact-id/version/name), wrong types, unknown parent info, or malformed dependency entries.

Common situations: Hand-edited quarkus-extension.yaml; third-party/legacy extensions produced by old tooling; generated descriptors from custom build integrations missing newly-required schema fields after a Quarkus upgrade.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unable to determine groupId and artifactId of the jar that c
• Unable to write the model to: ${yamlModelPath}
• Failed to locate 'artifact' or 'group-id' and 'artifact-id'
• OidcConfigurationMetadata can not be injected
• Metadata key already exists:

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