quarkusio/quarkus · error · IllegalArgumentException

A blocking route cannot be a failure route

Error message

A blocking route cannot be a failure route

What it means

RouteBuildItem.Builder.asFailureRoute() marks the handler as a failure (exception) handler; a handler already marked BLOCKING cannot be converted, and the builder throws this IllegalArgumentException to keep the two handler types mutually exclusive.

Source

Thrown at extensions/vertx-http/deployment-spi/src/main/java/io/quarkus/vertx/http/deployment/spi/RouteBuildItem.java:361

         * @return the current builder
         */
        public Builder asBlockingRoute() {
            if (this.typeOfHandler == HandlerType.FAILURE) {
                throw new IllegalArgumentException("A failure route cannot be a blocking route");
            }
            this.typeOfHandler = HandlerType.BLOCKING;
            return this;
        }

        /**
         * Sets the route as a failure route.
         * A failure route handler is invoked when an exception is thrown from a route handler.
         *
         * @return the current builder
         */
        public Builder asFailureRoute() {
            if (this.typeOfHandler == HandlerType.BLOCKING) {
                throw new IllegalArgumentException("A blocking route cannot be a failure route");
            }
            this.typeOfHandler = HandlerType.FAILURE;
            return this;
        }

        /**
         * Adds the route to the page returned when a 404 error is returned.
         *
         * @return the current builder
         */
        public Builder displayOnNotFoundPage() {
            this.displayOnNotFoundPage = true;
            return this;
        }

        /**
         * Adds the route to the page returned when a 404 error is returned, and sets the title of the page.
         *

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove asBlockingRoute() if the route should be a plain failure route
2. Remove asFailureRoute() if the route should stay blocking
3. Create a separate failure-route build item rather than converting the blocking one

Example fix

// before
RouteBuildItem.builder().route(route).asBlockingRoute().asFailureRoute().build()
// after
RouteBuildItem.builder().route(route).asFailureRoute().build()

// decide the handler type once; never apply both
boolean blocking = ...;
RouteBuildItem.Builder b = RouteBuildItem.builder().route(route);
if (blocking) b.asBlockingRoute(); else b.asFailureRoute();

When it happens

Trigger: Builder chain calls asBlockingRoute() then asFailureRoute() on the same builder (typeOfHandler == HandlerType.BLOCKING).

Common situations: Toggling an existing blocking route to be a failure route; a shared builder helper applying both flags; assuming the two modes compose rather than conflict.

Related errors

• A failure route cannot be a blocking route
• GeneratedStaticResourceBuildItem endpoint must start with '/
• GeneratedStaticResourceBuildItem endpoint must not end with
• Invalid fileName
• CardAction title is required

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