quarkusio/quarkus · error · IllegalStateException

Failed to resolve required property ${name}

Error message

Failed to resolve required property ${name}

What it means

Thrown by ToolsUtils.requireProperty when a required property is missing (null) from the provided Properties object. It is a fast-fail guard used when reading tool configuration properties (e.g. plugin artifact ids, versions) that must always be present.

Source

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

                                    return e.getKey();
                                }
                                String key = e.getKey();
                                if ("dockerfile.native-micro".equals(key)) {
                                    key += ".from";
                                }

                                return "tooling-dockerfiles." + key;
                            },
                            Entry::getValue, (v1, v2) -> v1));
        }

        return projectData;
    }

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

    public static String getMavenPluginArtifactId(Properties props) {
        return props.getProperty(ToolsConstants.PROP_QUARKUS_MAVEN_PLUGIN_ARTIFACT_ID);
    }

    public static String getMavenPluginGroupId(Properties props) {
        return props.getProperty(ToolsConstants.PROP_QUARKUS_MAVEN_PLUGIN_GROUP_ID);
    }

    public static String getQuarkusCoreVersion(Properties props) {
        return props.getProperty(ToolsConstants.PROP_QUARKUS_CORE_VERSION);
    }

    public static String requireQuarkusCoreVersion(Properties props) {
        return requireProperty(props, ToolsConstants.PROP_QUARKUS_CORE_VERSION);

View on GitHub (pinned to e1c734241f)

Solutions

  1. Identify the missing property from the message and add it to the properties source
  2. Restore the original unmodified properties file shipped with the tooling
  3. Ensure Maven resource filtering/placeholder substitution ran so ${...} placeholders got real values
  4. Check that you are using matching versions of the tools and properties resources

Example fix

// before: quarkus.properties missing the key
# quarkus-maven-plugin-artifact-id absent
// after
quarkus-maven-plugin-artifact-id=quarkus-maven-plugin
quarkus-maven-plugin-group-id=io.quarkus
Defensive patterns

Strategy: validation

Validate before calling

// Instead of requireProperty failing at runtime, check presence first
if (!props.containsKey(name)) {
    throw new IllegalStateException("Property " + name + " missing; check your properties file");
}

Try / catch

try {
    String v = ToolsUtils.requireProperty(props, name);
} catch (IllegalStateException e) {
    // fall back to a default or report the missing key: e.getMessage() minus prefix is the key
    throw e;
}

Prevention

When it happens

Trigger: Calling requireProperty(props, name) where props does not contain key 'name' — typically a properties file (quarkus.properties bundled constants) that was truncated, customized, or from a mismatched build.

Common situations: Hand-edited or filtered-out properties file; using tool constants JAR from a different Quarkus version; resource filtering disabled so placeholders were not substituted.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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