quarkusio/quarkus · error · IllegalArgumentException

`priority` must be positive

Error message

`priority` must be positive

What it means

FilterBuildItem requires a non-negative integer priority used to sort HTTP filters. The checkPriority method (called from the constructor) throws IllegalArgumentException with '`priority` must be positive' when a negative priority is passed. Despite the message saying 'positive', the check is priority < 0, so zero is accepted.

Source

Thrown at extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/FilterBuildItem.java:72

     * Creates a new instance of {@link FilterBuildItem} with an authentication failure handler.
     * The handler will be added as next to last, right before {@link io.quarkus.vertx.http.runtime.QuarkusErrorHandler}.
     */
    public static FilterBuildItem ofAuthenticationFailureHandler(Handler<RoutingContext> authFailureHandler) {
        return new FilterBuildItem(authFailureHandler);
    }

    /**
     * Creates a new instance of {@link FilterBuildItem} with an authentication failure handler.
     * The handler will be added right before any handlers added by
     * {@link FilterBuildItem#ofAuthenticationFailureHandler(Handler)}
     */
    public static FilterBuildItem ofPreAuthenticationFailureHandler(Handler<RoutingContext> authFailureHandler) {
        return new FilterBuildItem(authFailureHandler, SecurityHandlerPriorities.AUTH_FAILURE_HANDLER + 1, false, true);
    }

    private void checkPriority(int priority) {
        if (priority < 0) {
            throw new IllegalArgumentException("`priority` must be positive");
        }
    }

    public Handler<RoutingContext> getHandler() {
        return handler;
    }

    public int getPriority() {
        return priority;
    }

    public boolean isFailureHandler() {
        return isFailureHandler;
    }

    /**
     * @return a filter object wrapping the handler and priority.
     */

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass a non-negative priority (0 or greater) to the FilterBuildItem constructor
2. Clamp computed priorities: Math.max(0, basePriority - offset)
3. Use existing constants like SecurityHandlerPriorities to derive safe values

Example fix

// before
new FilterBuildItem(handler, MY_BASE_PRIORITY - 10); // negative

// after
new FilterBuildItem(handler, Math.max(0, MY_BASE_PRIORITY - 10));

int priority = computePriority();
if (priority < 0) {
    throw new IllegalArgumentException("Filter priority must be >= 0, got " + priority);
}
FilterBuildItem item = new FilterBuildItem(handler, priority);

When it happens

Trigger: Constructing new FilterBuildItem(handler, priority) or any of(...) factory with a negative int, typically from a computed priority constant that underflows or from subtracting from a base priority past zero.

Common situations: Custom extensions producing FilterBuildItems with hand-computed priorities; arithmetic on priority constants (e.g. BASE - offset) that goes negative; typos in literal priorities like -10.

Related errors

• Offending class is '${className}'
• Invalid fileName
• CardAction title is required
• CardText requires either staticText(), dynamicText(), or str
• Not enough information to build the page. Set at least one o

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