quarkusio/quarkus · error · IOException

Could not locate quarkus.properties on the classpath

Error message

Could not locate quarkus.properties on the classpath

What it means

loadQuarkusProperties throws this IOException when the resource 'quarkus.properties' cannot be found via Thread.currentThread().getContextClassLoader().getResourceAsStream. This file carries the Quarkus-supported Maven version range, so without it the enforcer cannot proceed. It is surfaced to users wrapped as 'Failed to ensure Quarkus Maven version compatibility'.

Source

Thrown at devtools/maven/src/main/java/io/quarkus/maven/components/MavenVersionEnforcer.java:42

            throw new MojoExecutionException("Failed to ensure Quarkus Maven version compatibility", e);
        }
        String mavenVersion = session.getSystemProperties().getProperty("maven.version");
        if (log.isDebugEnabled()) {
            log.debug("Detected Maven Version: " + mavenVersion);
        }
        DefaultArtifactVersion detectedVersion = new DefaultArtifactVersion(mavenVersion);
        enforce(log, supported, detectedVersion);
    }

    private static String getSupportedMavenVersions() throws IOException {
        return loadQuarkusProperties().getProperty("supported-maven-versions");
    }

    private static Properties loadQuarkusProperties() throws IOException {
        final String resource = "quarkus.properties";
        try (InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(resource)) {
            if (is == null) {
                throw new IOException("Could not locate " + resource + " on the classpath");
            }
            final Properties props = new Properties();
            try {
                props.load(is);
            } catch (IOException e) {
                throw new IOException("Failed to load " + resource + " from the classpath", e);
            }
            return props;
        }
    }

    /**
     * Compares the specified Maven version to see if it is allowed by the defined version range.
     *
     * @param log the log
     * @param requiredMavenVersionRange range of allowed versions for Maven.
     * @param actualMavenVersion the version to be checked.
     * @throws MojoExecutionException the given version fails the enforcement rule

View on GitHub (pinned to e1c734241f)

Solutions

1. Delete and re-download the plugin: rm -rf ~/.m2/repository/io/quarkus/quarkus-maven-plugin then run ./mvnw -U <goal>
2. Ensure you invoke the enforcer through the quarkus-maven-plugin rather than embedding MavenVersionEnforcer in your own plugin without a dependency on the quarkus-maven-plugin jar
3. Verify the plugin jar contains quarkus.properties: unzip -l ~/.m2/repository/io/quarkus/quarkus-maven-plugin/<ver>/quarkus-maven-plugin-<ver>.jar | grep quarkus.properties
4. Use a full official Quarkus release and matching plugin version in pom.xml

Example fix

// before (calling enforcer from a custom plugin without the resource on classpath)
new MavenVersionEnforcer().ensureMavenVersion(log, session);
// after (depend on quarkus-maven-plugin so quarkus.properties is packaged, or run it via the Quarkus plugin)
<plugin>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-maven-plugin</artifactId>
  <version>${quarkus.version}</version>
</plugin>

try (var is = Thread.currentThread().getContextClassLoader()
        .getResourceAsStream("quarkus.properties")) {
    if (is == null) throw new IllegalStateException("quarkus.properties not on classpath; reinstall quarkus-maven-plugin");
}

When it happens

Trigger: Calling getSupportedMavenVersions (from ensureMavenVersion) while the thread context classloader cannot resolve quarkus.properties — typically because the quarkus-maven-plugin jar in the local repo is missing the resource or the classloader is not the plugin's.

Common situations: Corrupted/partially downloaded quarkus-maven-plugin artifact in ~/.m2; manually repackaged or shaded plugin jar; running code that calls MavenVersionEnforcer outside the Quarkus Maven plugin so the resource is not on the context classloader.

Related errors

• Failed to locate io.quarkus:quarkus-core-deployment on the a
• Failed to load CodeGenProvider class from deployment classlo
• Failed to read %s
• Failed to read resources from classpath
• Failed to open class path file <file>

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