quarkusio/quarkus · error · RuntimeException

The '%s' can only be used on Jakarta REST or WebSockets Next

Error message

The '%s' can only be used on Jakarta REST or WebSockets Next endpoints

What it means

Eager security interceptors like @AuthenticationContext can only be applied to Jakarta REST endpoints or WebSockets Next endpoints. If the application has neither the RESTEasy/RESTEasy-Reactive nor the WebSockets-Next capability, the build step throws RuntimeException since there is no supported target for the interceptor.

Source

Thrown at extensions/oidc/deployment/src/main/java/io/quarkus/oidc/deployment/OidcBuildStep.java:552

    @Record(ExecutionTime.STATIC_INIT)
    @BuildStep
    FilterBuildItem registerResourceMetadataHandler(OidcBuildTimeConfig buildTimeConfig,
            BeanContainerBuildItem beanContainerBuildItem, OidcRecorder recorder) {
        if (!isRouteAllowed(buildTimeConfig, OidcRoute.RESOURCE_METADATA)) {
            return null;
        }
        Handler<RoutingContext> handler = recorder.getResourceMetadataHandler(beanContainerBuildItem.getValue());
        return new FilterBuildItem(handler, SecurityHandlerPriorities.AUTHORIZATION - 50);
    }

    private static boolean areEagerSecInterceptorsSupported(Capabilities capabilities,
            VertxHttpBuildTimeConfig httpBuildTimeConfig) {
        if (httpBuildTimeConfig.auth().proactive()) {
            throw new RuntimeException("The '%s' annotation is only supported when proactive authentication is disabled"
                    .formatted(AUTHENTICATION_CONTEXT_NAME));
        } else if (capabilities.isMissing(Capability.WEBSOCKETS_NEXT) && capabilities.isMissing(Capability.RESTEASY_REACTIVE)
                && capabilities.isMissing(Capability.RESTEASY)) {
            throw new RuntimeException("The '%s' can only be used on Jakarta REST or WebSockets Next endpoints");
        }
        return true;
    }

    private static boolean isInjected(BeanRegistrationPhaseBuildItem beanRegistrationPhaseBuildItem, DotName requiredType,
            DotName withoutQualifier) {
        for (InjectionPointInfo injectionPoint : beanRegistrationPhaseBuildItem.getInjectionPoints()) {
            if (requiredType.equals(injectionPoint.getRequiredType().name())
                    && isApplicationPackage(injectionPoint.getTargetInfo())
                    && (withoutQualifier == null || injectionPoint.getRequiredQualifier(withoutQualifier) == null)) {
                LOG.debugf("%s injection point: %s", requiredType.toString(), injectionPoint.getTargetInfo());
                return true;
            }
        }
        return false;
    }

    private static boolean isApplicationPackage(String injectionPointTargetInfo) {

View on GitHub (pinned to e1c734241f)

Solutions

Add the quarkus-rest (RESTEasy Reactive) dependency
Or add quarkus-websockets-next if using WebSockets Next endpoints
Remove the @AuthenticationContext annotation if the app has no supported endpoint type

Example fix

// before
<!-- no REST dependency -->
// after
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-rest</artifactId>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

// Ensure one of these dependencies exists before using @AuthenticationContext:
// io.quarkus:quarkus-rest, io.quarkus:quarkus-resteasy, or io.quarkus:quarkus-websockets-next

Try / catch

try { Quarkus.run(args); } catch (RuntimeException e) { if (e.getMessage().contains("can only be used on Jakarta REST or WebSockets Next endpoints")) { /* add missing dependency */ } }

Prevention

Add quarkus-rest or quarkus-websockets-next when adopting OIDC auth annotations
Do not copy annotations into apps without the matching extension
Check capabilities via the Quarkus build report

When it happens

Trigger: Adding @AuthenticationContext in an application lacking resteasy-reactive, resteasy, and websockets-next dependencies (capabilities missing), detected via Capabilities in the build step.

Common situations: Quarkus REST (or legacy REST) not on the classpath, e.g. a gRPC/Vert.x-only app; annotation copied from another project without adding the REST dependency.

Related errors

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