What causes "Failed to resolve required property " in quarkusio/quarkus?

Set the property explicitly, e.g. -D = on the Maven/Java command line

quarkusio/quarkus · error · IllegalStateException

Failed to resolve required property <name>

Error message

Failed to resolve required property <name>

What it means

ToolsUtils.requireProperty looks up a required system/environment property and throws IllegalStateException if it is absent. This signals that a mandatory configuration input (typically a Quarkus tool property like quarkus.platform.* or registry settings) was not provided to the tool.

Source

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

import io.quarkus.bootstrap.BootstrapConstants;
import io.quarkus.bootstrap.resolver.AppModelResolver;
import io.quarkus.bootstrap.resolver.BootstrapAppModelResolver;
import io.quarkus.bootstrap.resolver.maven.MavenArtifactResolver;
import io.quarkus.devtools.messagewriter.MessageWriter;
import io.quarkus.maven.dependency.ArtifactCoords;
import io.quarkus.registry.CatalogMergeUtility;
import io.quarkus.registry.Constants;
import io.quarkus.registry.catalog.ExtensionCatalog;
import io.quarkus.registry.catalog.selection.OriginPreference;
import io.quarkus.registry.util.PlatformArtifacts;

public class ToolsUtils {

    public static String requireProperty(String name) {
        final String value = getProperty(name);
        if (value == null) {
            throw new IllegalStateException("Failed to resolve required property " + name);
        }
        return value;
    }

    public static String getProperty(String name) {
        return getProperty(name, null);
    }

    public static String getProperty(String name, String defaultValue) {
        return System.getProperty(name, defaultValue);
    }

    public static Map<String, String> stringToMap(
            String str, String entrySeparator, String keyValueSeparator) {
        HashMap<String, String> result = new HashMap<>();
        for (String entry : StringUtils.splitByWholeSeparator(str, entrySeparator)) {
            String[] pair = StringUtils.splitByWholeSeparator(entry, keyValueSeparator, 2);

View on GitHub (pinned to e1c734241f)

Solutions

Set the property explicitly, e.g. -D<name>=<value> on the Maven/Java command line
Export the corresponding environment variable in your shell/CI environment
Check Maven settings.xml / plugin <properties> configuration for the missing key

Example fix

// before
mvn quarkus:create-extension   # missing required property
// after
mvn quarkus:create-extension -Dquarkus.platform.version=3.2.0.Final

Defensive patterns

Strategy: try-catch

Validate before calling

String val = ToolsUtils.getProperty("quarkus.platform.version");
if (val == null || val.isBlank()) {
    throw new IllegalStateException("Set -Dquarkus.platform.version before invoking tooling");
}

Try / catch

try {
    String v = ToolsUtils.requireProperty("quarkus.platform.version");
} catch (IllegalStateException e) {
    // e.getMessage() names the missing property; fail fast with guidance
    throw new IllegalStateException(e.getMessage() + " — pass it via -D or env var", e);
}

Prevention

Pass all -D properties in CI scripts, not just locally
Document required properties next to tool invocations
Prefer explicit plugin <properties> configuration over reliance on ambient env vars

When it happens

Trigger: Calling requireProperty(name) where getProperty(name) returns null: the system property is not set on the command line, the environment variable backing it is missing, or the properties file was not loaded.

Common situations: Running quarkus-maven-plugin / CLI goals without -D flags; CI environments missing exported variables that exist locally; Maven settings not passing properties through plugin configuration.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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