quarkusio/quarkus · error · RuntimeException

Failed to locate quarkus.properties on the classpath

Error message

Failed to locate quarkus.properties on the classpath

What it means

VersionHelper.clientVersion reads quarkus.properties from the classpath to report the Quarkus client version. If the context ClassLoader cannot locate that resource, it throws a RuntimeException stating the properties file is missing — indicating a broken/incomplete CLI distribution or packaging.

Source

Thrown at devtools/cli-common/src/main/java/io/quarkus/cli/common/VersionHelper.java:25

import java.util.Properties;

import io.quarkus.runtime.util.ClassPathUtils;

/**
 * Helper class to get client version without circular dependencies
 */
public class VersionHelper {
    private static String version;

    public static String clientVersion() {
        if (version != null) {
            return version;
        }

        final Properties props = new Properties();
        final URL quarkusPropertiesUrl = Thread.currentThread().getContextClassLoader().getResource("quarkus.properties");
        if (quarkusPropertiesUrl == null) {
            throw new RuntimeException("Failed to locate quarkus.properties on the classpath");
        }

        // we have a special case for file and jar as using getResourceAsStream() on Windows might cause file locks
        if ("file".equals(quarkusPropertiesUrl.getProtocol()) || "jar".equals(quarkusPropertiesUrl.getProtocol())) {
            ClassPathUtils.consumeAsPath(quarkusPropertiesUrl, p -> {
                try (BufferedReader reader = Files.newBufferedReader(p)) {
                    props.load(reader);
                } catch (IOException e) {
                    throw new RuntimeException("Failed to load quarkus.properties", e);
                }
            });
        } else {
            try {
                props.load(Thread.currentThread().getContextClassLoader().getResourceAsStream("quarkus.properties"));
            } catch (IOException e) {
                throw new IllegalStateException("Failed to load quarkus.properties", e);
            }
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Rebuild/reinstall the Quarkus CLI (e.g. via jbang or the installer) so the packaged quarkus.properties is present.
2. If building locally, run the full Maven build for devtools/cli so resource filtering includes quarkus.properties.
3. Check the launcher's classpath: run via the official `quarkus` entry point rather than invoking the jar class manually.

Example fix

// before (broken packaging)
mvn -f devtools/cli package -DskipResources
// after
./mvnw install -f devtools/cli -DskipTests

URL u = Thread.currentThread().getContextClassLoader().getResource("quarkus.properties");
if (u == null) {
    throw new IllegalStateException("quarkus.properties missing; reinstall/repair the Quarkus CLI");
}

try {
    String v = VersionHelper.clientVersion();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Failed to locate quarkus.properties")) {
        log.warn("Broken CLI installation; bypassing version lookup");
    } else throw e;
}

When it happens

Trigger: Calling VersionHelper.clientVersion() (used by CLI commands reporting versions) when the runtime classpath contains no quarkus.properties resource, i.e. quarkusPropertiesUrl == null.

Common situations: Running the CLI from a partially built or repackaged jar where resource filtering/packaging was skipped; shaded/fat-jar builds excluding the properties file; executing classes outside the normal CLI launcher (e.g. from an IDE without the CLI resources on the classpath).

Related errors

• Failed to load quarkus.properties
• Failed to locate quarkus-core-version property in the bundle
• Unable to find or load top command: <className>
• Failed to load extension metadata schema from <schemaResourc
• Expected : after attribute

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