quarkusio/quarkus · error · IllegalArgumentException

orderKey must be present and not empty

Error message

orderKey must be present and not empty

What it means

VertxBootstrapConsumerBuildItem is a deployment SPI build item carrying a Consumer<VertxBootstrap> with a priority and a stable orderKey used to sort consumers deterministically. The constructor rejects a null or empty orderKey because ordering without a stable key is undefined.

Source

Thrown at extensions/vertx/deployment-spi/src/main/java/io/quarkus/vertx/deployment/spi/VertxBootstrapConsumerBuildItem.java:33

 * after VertxOptions customizers have been applied.
 * <p>
 * Unlike {@link VertxOptionsConsumerBuildItem}, there is no runtime alternative. {@link VertxBootstrap} being an
 * internal API, only extensions can customize it, and they must do so at build time.
 */
public final class VertxBootstrapConsumerBuildItem extends MultiBuildItem
        implements Comparable<VertxBootstrapConsumerBuildItem> {
    private final Consumer<VertxBootstrap> consumer;
    private final int priority;
    private final String orderKey;

    /**
     * @param consumer the consumer to apply to VertxBootstrap
     * @param priority consumers are called from lowest to highest priority
     * @param orderKey a stable key used to order consumers with the same priority
     */
    public VertxBootstrapConsumerBuildItem(Consumer<VertxBootstrap> 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<VertxBootstrap> getConsumer() {
        return consumer;
    }

    @Override
    public int compareTo(VertxBootstrapConsumerBuildItem 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. Pass a non-empty stable string literal as orderKey (e.g. "my-extension-bootstrap")
  2. Derive the key from a config property with a documented default
  3. Fix extension code still calling an older constructor signature
  4. If the key comes from config, validate the config before creating the build item

Example fix

// before
new VertxBootstrapConsumerBuildItem(consumer, 100, config.key()); // may be null

// after
new VertxBootstrapConsumerBuildItem(consumer, 100,
    Objects.requireNonNullElse(config.key(), "myext-bootstrap"));
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: An extension's build step constructs new VertxBootstrapConsumerBuildItem(consumer, priority, orderKey) with orderKey == null or "" (e.g. from an unset config value or missing constant).

Common situations: Extension authors wiring bootstrap customization from configuration where the key property is unset; copy-pasting the two-argument constructor from an older API that had no orderKey.

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/d1436bb4b4bed2f5. Report an issue: GitHub.