quarkusio/quarkus · error · IOException

Failed to load extension metadata schema from <schemaResourc

Error message

Failed to load extension metadata schema from <schemaResource>

What it means

ExtensionMetadataValidator.validate loads the JSON schema bundled with the tools (ToolsConstants.EXTENSION_SCHEMA_RESOURCE) from the classpath to validate a quarkus-extension.yaml descriptor object. If the schema resource cannot be found on the classpath, it throws IOException with this message.

Source

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

 * This class is shared by the extension Maven plugin and the extension Gradle plugin so that the
 * validation logic is not duplicated.
 */
public final class ExtensionMetadataValidator {

    private ExtensionMetadataValidator() {
    }

    /**
     * Validates the given extension descriptor against the bundled JSON schema.
     *
     * @param extObject the extension descriptor
     * @throws IOException if the schema cannot be loaded or the descriptor is invalid
     */
    public static void validate(ObjectNode extObject) throws IOException {
        final Schema schema;
        try (InputStream is = ExtensionMetadataValidator.class.getResourceAsStream(ToolsConstants.EXTENSION_SCHEMA_RESOURCE)) {
            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. Verify quarkus-devtools-common on the classpath contains the schema resource (open the jar and check for the resource under ToolsConstants.EXTENSION_SCHEMA_RESOURCE)
2. Rebuild/reinstall the quarkus-devtools-common module so the schema is packaged
3. Check for resource-exclusion filters (maven-shade/maven-jar resource includes) and add the schema resource

Example fix

// pom.xml shade config
// before
<exclude>**/*.json</exclude>
// after
<exclude>**/*.json</exclude>
<exclude>schema/extension-metadata.json</exclude> <!-- keep it, or remove this pattern -->
(adjust: do NOT exclude ToolsConstants.EXTENSION_SCHEMA_RESOURCE)

String res = ToolsConstants.EXTENSION_SCHEMA_RESOURCE;
if (ExtensionMetadataValidator.class.getResourceAsStream(res) == null) {
    throw new IllegalStateException("Schema resource missing from classpath: " + res);
}
ExtensionMetadataValidator.validate(extObject);

try {
    ExtensionMetadataValidator.validate(extObject);
} catch (IOException e) {
    if (e.getMessage().startsWith("Failed to load extension metadata schema")) {
        throw new IllegalStateException("quarkus-devtools-common jar is incomplete or mis-shaded", e);
    }
    throw e;
}

When it happens

Trigger: Calling ExtensionMetadataValidator.validate in an environment where the schema resource is absent — schema file removed from the jar, shaded/fat jar excluding it, or a broken dependency (wrong devtools-common version) on the classpath.

Common situations: Custom builds with resource filtering excluding .json schema files; running tools from an incomplete classpath; classloader issues in isolated environments (e.g. Maven plugin realms) hiding the resource.

Related errors

• Failed to locate quarkus.properties on the classpath
• Expected : after attribute
• Failed to load CodeGenProvider class from deployment classlo
• 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/95cfe42f4fafc9dc. Report an issue: GitHub.