quarkusio/quarkus · error · java.lang.IllegalStateException

Unknown type

Error message

Unknown type 

What it means

ReactiveRoutesProcessor.addAdditionalRoutes maps a route handler method's @Route type annotation to an internal HandlerType. Only NORMAL, BLOCKING and FAILURE are supported; any other RouteHandlerType enum constant (e.g. from a future/unknown API) hits the default branch and throws IllegalStateException.

Source

Thrown at extensions/reactive-routes/deployment/src/main/java/io/quarkus/vertx/web/deployment/ReactiveRoutesProcessor.java:424

                    }
                } else {
                    regex = regexValue.asString();
                }

                if (route.value(VALUE_PRODUCES) == null && baseProduces != null) {
                    produces = baseProduces;
                }
                if (route.value(VALUE_CONSUMES) == null && baseConsumes != null) {
                    consumes = baseConsumes;
                }

                HandlerType handlerType = HandlerType.NORMAL;
                if (routeHandlerType != null) {
                    handlerType = switch (routeHandlerType) {
                        case NORMAL -> HandlerType.NORMAL;
                        case BLOCKING -> HandlerType.BLOCKING;
                        case FAILURE -> HandlerType.FAILURE;
                        default -> throw new IllegalStateException("Unknown type " + routeHandlerType);
                    };
                }

                if (businessMethod.isBlocking()) {
                    if (handlerType == HandlerType.NORMAL) {
                        handlerType = HandlerType.BLOCKING;
                    } else if (handlerType == HandlerType.FAILURE) {
                        throw new IllegalStateException(
                                "Invalid combination - a reactive route cannot use @Blocking and use the type `failure` at the same time: "
                                        + businessMethod.getMethod().toString());
                    }
                }

                if (routeHandler == null) {
                    String handlerClass = generateHandler(
                            new HandlerDescriptor(businessMethod.getMethod(), beanValidationAnnotations.orElse(null),
                                    handlerType == HandlerType.FAILURE, produces),
                            businessMethod.getBean(), businessMethod.getMethod(), gizmo, transformedAnnotations,

View on GitHub (pinned to e1c734241f)

Solutions

1. Use only type = RouteHandlerType.NORMAL, BLOCKING, or FAILURE on @Route methods
2. Align quarkus-vertx-http and reactive-routes versions (upgrade the whole Quarkus BOM together)
3. Check imports so the annotation uses io.quarkus.vertx.web.RouteFilter/route types, not a custom enum

Example fix

// before
@Route(path = "/x", type = RouteHandlerType.OTHER)
// after
@Route(path = "/x", type = RouteHandlerType.NORMAL)

RouteHandlerType t = route.type();
if (t != RouteHandlerType.NORMAL
        && t != RouteHandlerType.BLOCKING
        && t != RouteHandlerType.FAILURE) {
    throw new IllegalStateException("Unsupported @Route type: " + t);
}

boolean isSupported(RouteHandlerType t) {
    return switch (t) {
        case NORMAL, BLOCKING, FAILURE -> true;
        default -> false;
    };
}

When it happens

Trigger: Annotating a method with @Route(type = ...) whose RouteHandlerType value is not NORMAL/BLOCKING/FAILURE — possible with new enum constants added upstream that the processor doesn't yet handle.

Common situations: Using a newer quarkus-vertx-http API enum constant with an older reactive-routes processor; custom enum implementations; IDE auto-import of a wrong similarly named type.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid combination - a reactive route cannot use @Blocking
• Route filter method must return void [method: %s, bean: %s]
• Route filter method must accept exactly one parameter of typ
• Unsupported param type: " + paramType
• @ConsumeEvent annotation must target a method

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