quarkusio/quarkus · error · IllegalArgumentException

Failed to format option ${DASH_XX_COLLON + getName()} with v

Error message

Failed to format option ${DASH_XX_COLLON + getName()} with values ${getValues()}

What it means

MutableXxJvmOption.toCliOptions() converts an -XX option's stored values into -XX:... CLI flags. It handles true/false/'+'/'-' boolean values and single key=value pairs; if the value set has any other shape (multiple values or an unrecognized value on a multi-valued option) it cannot be represented as CLI flags and throws this IllegalArgumentException.

Source

Thrown at independent-projects/bootstrap/app-model/src/main/java/io/quarkus/bootstrap/model/MutableXxJvmOption.java:59

        return COMPLETE_PROPERTY_PREFIX;
    }

    @Override
    public List<String> toCliOptions() {
        if (!hasValue()) {
            return toBooleanOption(true);
        }
        if (getValues().size() == 1) {
            var value = getValues().iterator().next();
            if ("true".equalsIgnoreCase(value) || "+".equals(value)) {
                return toBooleanOption(true);
            }
            if ("false".equalsIgnoreCase(value) || "-".equals(value)) {
                return toBooleanOption(false);
            }
            return List.of(DASH_XX_COLLON + getName() + "=" + value);
        }
        throw new IllegalArgumentException(
                "Failed to format option " + DASH_XX_COLLON + getName() + " with values " + getValues());
    }

    private List<String> toBooleanOption(boolean enabled) {
        return List.of(DASH_XX_COLLON + (enabled ? "+" : "-") + getName());
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

Ensure each -XX option carries exactly one value (use separate options for distinct values)
Use recognized boolean literals ('true','false','+','-') for boolean -XX options
If you control the input, normalize the option's values before invoking toCliOptions()

Example fix

// before
xxOption.addValue("PerfDisableSharedMem").addValue("UseAES");
// after
xxOption.addValue("PerfDisableSharedMem");
XxJvmOption other = new MutableXxJvmOption("UseAES").addValue("true");

Defensive patterns

Strategy: validation

Validate before calling

boolean isFormattableXx(MutableXxJvmOption o) {
    var values = o.getValues();
    return values.size() <= 1;
}
// call only when isFormattableXx(option) is true

Type guard

boolean isSingleValued(Collection<String> v) { return v.size() <= 1; }

Try / catch

try {
    List<String> cli = xxOption.toCliOptions();
} catch (IllegalArgumentException e) {
    log.errorf("Cannot serialize -XX option %s to CLI: %s", xxOption.getName(), e.getMessage());
}

Prevention

Keep one value per -XX option; split multi-values into separate options
Use only true/false/+/- for boolean -XX flags
Prefer the Properties representation for multi-valued options instead of CLI form

When it happens

Trigger: Calling toCliOptions() on an -XX option that has multiple values, or a value that is not 'true'/'false'/'+'/'-' and the option ended up with more than one entry so no single 'name=value' form can be produced.

Common situations: Adding several values to an -XX option via addValue with '|' or repeated calls, then serializing to CLI; migrating options between Properties form (which supports '|'-separated multi-values) and CLI form.

Related errors

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