{"record":{"id":"d60b8901984cfba5","repo":"quarkusio/quarkus","slug":"a-blocking-route-cannot-be-a-failure-route","errorCode":null,"errorMessage":"A blocking route cannot be a failure route","messagePattern":"A blocking route cannot be a failure route","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/deployment-spi/src/main/java/io/quarkus/vertx/http/deployment/spi/RouteBuildItem.java","lineNumber":361,"sourceCode":"         * @return the current builder\n         */\n        public Builder asBlockingRoute() {\n            if (this.typeOfHandler == HandlerType.FAILURE) {\n                throw new IllegalArgumentException(\"A failure route cannot be a blocking route\");\n            }\n            this.typeOfHandler = HandlerType.BLOCKING;\n            return this;\n        }\n\n        /**\n         * Sets the route as a failure route.\n         * A failure route handler is invoked when an exception is thrown from a route handler.\n         *\n         * @return the current builder\n         */\n        public Builder asFailureRoute() {\n            if (this.typeOfHandler == HandlerType.BLOCKING) {\n                throw new IllegalArgumentException(\"A blocking route cannot be a failure route\");\n            }\n            this.typeOfHandler = HandlerType.FAILURE;\n            return this;\n        }\n\n        /**\n         * Adds the route to the page returned when a 404 error is returned.\n         *\n         * @return the current builder\n         */\n        public Builder displayOnNotFoundPage() {\n            this.displayOnNotFoundPage = true;\n            return this;\n        }\n\n        /**\n         * Adds the route to the page returned when a 404 error is returned, and sets the title of the page.\n         *","sourceCodeStart":343,"sourceCodeEnd":379,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/deployment-spi/src/main/java/io/quarkus/vertx/http/deployment/spi/RouteBuildItem.java#L343-L379","documentation":"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.","triggerScenarios":"Builder chain calls asBlockingRoute() then asFailureRoute() on the same builder (typeOfHandler == HandlerType.BLOCKING).","commonSituations":"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.","solutions":["Remove asBlockingRoute() if the route should be a plain failure route","Remove asFailureRoute() if the route should stay blocking","Create a separate failure-route build item rather than converting the blocking one"],"exampleFix":"// before\nRouteBuildItem.builder().route(route).asBlockingRoute().asFailureRoute().build()\n// after\nRouteBuildItem.builder().route(route).asFailureRoute().build()","handlingStrategy":"validation","validationCode":"// decide the handler type once; never apply both\nboolean blocking = ...;\nRouteBuildItem.Builder b = RouteBuildItem.builder().route(route);\nif (blocking) b.asBlockingRoute(); else b.asFailureRoute();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never chain asBlockingRoute().asFailureRoute()","Use separate RouteBuildItems for blocking and failure handling","Centralize route construction to enforce a single handler type"],"tags":["build-time","routes","validation","argument-illegal"],"backgroundTag":"incompatible-route-config","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}