quarkusio/quarkus · error · RuntimeException

Failed to locate META-INF/quarkus.properties in ${runtimeExt

Error message

Failed to locate META-INF/quarkus.properties in ${runtimeExtCompactCoords}

What it means

DevUIProcessor collects deployment coordinates by reading META-INF/quarkus.properties from each runtime extension artifact; the lookup returns null when no artifact on the classpath contains that descriptor file. This is thrown after the deployment-artifact scan fails to match the given runtime extension. It means a required Quarkus extension's runtime JAR lacks its extension descriptor.

Source

Thrown at extensions/devui/deployment/src/main/java/io/quarkus/devui/deployment/DevUIProcessor.java:1077

            if (extPropsVisit == null) {
                return null;
            }
            final Properties props = new Properties();
            try (BufferedReader reader = Files.newBufferedReader(extPropsVisit.getPath())) {
                props.load(reader);
            } catch (IOException e) {
                throw new RuntimeException("Failed to read " + extPropsVisit.getUrl(), e);
            }
            final String deploymentCoords = props.getProperty(BootstrapConstants.PROP_DEPLOYMENT_ARTIFACT);
            if (deploymentCoords == null) {
                throw new RuntimeException(
                        "Failed to locate " + BootstrapConstants.PROP_DEPLOYMENT_ARTIFACT + " in " + extPropsVisit.getUrl());
            }
            var coords = GACTV.fromString(deploymentCoords);
            return new GACT(coords.getGroupId(), coords.getArtifactId(), coords.getClassifier(), coords.getType());
        });
        if (result == null) {
            throw new RuntimeException("Failed to locate " + BootstrapConstants.DESCRIPTOR_PATH
                    + " in " + runtimeExt.toCompactCoords());
        }
        return result;
    }

    @BuildStep(onlyIf = IsLocalDevelopment.class)
    void createAllRoutes(WebJarResultsBuildItem webJarResultsBuildItem,
            LaunchModeBuildItem launchModeBuildItem,
            List<DevUIWebJarBuildItem> devUIWebJarBuiltItems,
            BuildProducer<DevUIRoutesBuildItem> devUIRoutesProducer) {

        if (launchModeBuildItem.isNotLocalDevModeType()) {
            return;
        }

        for (DevUIWebJarBuildItem devUIWebJarBuiltItem : devUIWebJarBuiltItems) {
            WebJarResultsBuildItem.WebJarResult result = webJarResultsBuildItem
                    .byArtifactKey(devUIWebJarBuiltItem.getArtifactKey());

View on GitHub (pinned to e1c734241f)

Solutions

Rebuild the extension named in the message with the standard Quarkus extension parent POM so the quarkus-maven-plugin generates META-INF/quarkus.properties.
Verify the runtime JAR actually contains META-INF/quarkus.properties: unzip -l <runtime-jar> | grep quarkus.properties.
Check for version mismatches between the runtime and deployment artifacts of that extension and align them with the Quarkus BOM.
Clean stale artifacts: remove the module from ~/.m2 and run ./mvnw clean install.

Example fix

// before (extension runtime pom.xml using plain maven-jar packaging, no descriptor)
<packaging>jar</packaging>

// after
<parent>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-extension-parent</artifactId>
</parent>
<packaging>jar</packaging> <!-- quarkus-extension-maven-plugin injects META-INF/quarkus.properties -->

Defensive patterns

Strategy: validation

Validate before calling

URL desc = classLoader.getResource("META-INF/quarkus.properties");
if (desc == null) {
    throw new IllegalStateException("Runtime extension JAR is missing META-INF/quarkus.properties: " + runtimeExt.toCompactCoords());
}

Try / catch

try { ... } catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to locate META-INF/quarkus.properties")) {
        log.errorf("Rebuild the extension %s with quarkus-extension tooling", e.getMessage());
    } else throw e;
}

Prevention

Run 'unzip -l <jar> | grep quarkus.properties' as a CI check for extension JARs
Use quarkus-extension-maven-plugin in runtime module builds
Avoid shading/repackaging extension JARs

When it happens

Trigger: The blocking call over extension quarkus.properties files returns no match for the runtime extension's coordinates, so result == null when building the GACT list for Dev UI; thrown with the runtime extension's compact coordinates in the message.

Common situations: A custom/in-house runtime JAR packaged without META-INF/quarkus.properties; a jar-in-jar or shaded deployment that dropped the descriptor; classpath ordering issues in a fat-jar; mixing extension versions so the runtime artifact doesn't match any scanned descriptor.

Related errors

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