quarkusio/quarkus · error · IllegalArgumentException

orderKey must be present and not empty

Error message

orderKey must be present and not empty

What it means

VertxOptionsConsumerBuildItem carries a Consumer<VertxOptions> applied when the Vert.x instance is configured, with a priority and a mandatory stable orderKey for deterministic sorting. The constructor throws IllegalArgumentException for a null or empty orderKey.

Source

Thrown at extensions/vertx/deployment-spi/src/main/java/io/quarkus/vertx/deployment/spi/VertxOptionsConsumerBuildItem.java:28

 * Vert.x system behavior, e.g. setting MetricsOptions to enable
 * and configure a metrics provider.
 * <p>
 * Consumers will be called in priority order (lowest to highest), then by order key,
 * after VertxConfiguration has been read and applied.
 */
public final class VertxOptionsConsumerBuildItem extends MultiBuildItem implements Comparable<VertxOptionsConsumerBuildItem> {
    private final Consumer<VertxOptions> consumer;
    private final int priority;
    private final String orderKey;

    /**
     * @param optionsConsumer the consumer to apply to VertxOptions
     * @param priority consumers are called from lowest to highest priority
     * @param orderKey a stable key used to order consumers with the same priority
     */
    public VertxOptionsConsumerBuildItem(Consumer<VertxOptions> consumer, int priority, String orderKey) {
        if (orderKey == null || orderKey.isEmpty()) {
            throw new IllegalArgumentException("orderKey must be present and not empty");
        }
        this.consumer = consumer;
        this.priority = priority;
        this.orderKey = orderKey;
    }

    public Consumer<VertxOptions> getConsumer() {
        return consumer;
    }

    @Override
    public int compareTo(VertxOptionsConsumerBuildItem o) {
        if (this == o) {
            return 0;
        }
        int result = Integer.compare(this.priority, o.priority);
        if (result != 0) {
            return result;

View on GitHub (pinned to e1c734241f)

Solutions

1. Supply a stable non-empty orderKey literal unique to your extension
2. Default the key from configuration with Objects.requireNonNullElse or @WithDefault in the config mapping
3. Validate configuration before constructing the build item
4. Update extension code to the current constructor signature

Example fix

// before
new VertxOptionsConsumerBuildItem(consumer, priority, null);

// after
new VertxOptionsConsumerBuildItem(consumer, priority, "myext-vertx-options");

Objects.requireNonNull(orderKey, "orderKey required");
if (orderKey.isEmpty()) throw new IllegalArgumentException("orderKey must not be empty");
new VertxOptionsConsumerBuildItem(consumer, priority, orderKey);

try {
    new VertxOptionsConsumerBuildItem(consumer, priority, key);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("VertxOptions consumer wiring failed: " + e.getMessage(), e);
}

When it happens

Trigger: Creating new VertxOptionsConsumerBuildItem(consumer, priority, orderKey) in a deployment build step with a null/empty orderKey, typically from an unset config value or forgotten argument.

Common situations: Extension authors customizing Vert.x options based on configuration where the key field is absent; porting code from the older constructor that had no orderKey parameter.

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

• orderKey must be present and not empty
• Two VertxBootstrapConsumerBuildItem instances have the same
• Two VertxOptionsConsumerBuildItem instances have the same pr
• Failed to find any non-blocking provider for startup actions
• No Vert.x instance has been registered in ArC ?

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