quarkusio/quarkus · error · IllegalStateException

WebSocket endpoint '%s' requires secured HTTP upgrade but Qu

Error message

WebSocket endpoint '%s' requires secured HTTP upgrade but Quarkus did not configure security check correctly. Please open issue in Quarkus project

What it means

WebSocket endpoints annotated with HTTP security annotations require a registered SecurityCheck so the HTTP upgrade request is authenticated/authorized. The processor found a security annotation on the endpoint class but no corresponding SecurityCheck in the storage, meaning the security extension did not wire the check. Per the message, this is treated as a Quarkus bug rather than user error.

Source

Thrown at extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/WebSocketProcessor.java:953

    }

    private static boolean isTracesSupportEnabled(Capabilities capabilities) {
        return capabilities.isPresent(Capability.OPENTELEMETRY_TRACER);
    }

    private static boolean isMetricsSupportEnabled(Optional<MetricsCapabilityBuildItem> metricsCapability) {
        return metricsCapability.map(m -> m.metricsSupported(MetricsFactory.MICROMETER)).orElse(false);
    }

    private static Map<String, SecurityCheck> collectEndpointSecurityChecks(List<WebSocketEndpointBuildItem> endpoints,
            ClassSecurityCheckStorageBuildItem storage, IndexView index, SecurityTransformer securityTransformer) {
        Map<String, SecurityCheck> endpointSecurityChecks = endpoints
                .stream().<Map.Entry<String, SecurityCheck>> mapMulti((endpoint, consumer) -> {
                    var beanName = endpoint.beanClassName();
                    if (storage.getSecurityCheck(beanName) instanceof SecurityCheck check) {
                        consumer.accept(Map.entry(endpoint.id, check));
                    } else if (securityTransformer.hasSecurityAnnotation(index.getClassByName(beanName))) {
                        throw new IllegalStateException("WebSocket endpoint '%s' requires ".formatted(beanName)
                                + "secured HTTP upgrade but Quarkus did not configure security check "
                                + "correctly. Please open issue in Quarkus project");
                    }
                })
                // Do not use Collectors.toUnmodifiableMap() here - its iteration order is not stable.
                // Instead, collect to a regular HashMap<K, V> and wrap it in Collections.unmodifiableMap()
                // down below.
                .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue, (previous, current) -> {
                    throw new IllegalStateException("Multiple WebSocket endpoints with the same id");
                }));
        return Collections.unmodifiableMap(endpointSecurityChecks);
    }

    private static Map<String, Set<String>> collectEndpointAuthorizationPolicies(SecurityTransformer securityTransformer,
            List<WebSocketEndpointBuildItem> endpoints, IndexView index) {
        long authorizationPoliciesCount = securityTransformer.getSecurityAnnotationNames(AUTHORIZATION_POLICY)
                .stream().mapToLong(n -> securityTransformer.getAnnotations(n).size()).sum();
        if (authorizationPoliciesCount == 0) {

View on GitHub (pinned to e1c734241f)

Solutions

Add/configure the Quarkus security extension (e.g. quarkus-security, quarkus-oidc, quarkus-smallrye-jwt) so security checks are registered.
Verify quarkus-websockets-next and quarkus-security come from the same Quarkus BOM version.
Report to the Quarkus project with a reproducer if versions align and the error persists.
As a workaround, secure the HTTP upgrade path explicitly (e.g. an HTTP security policy on the endpoint path) instead of annotation-driven security.

Example fix

// before
<dependency><groupId>io.quarkus</groupId><artifactId>quarkus-websockets-next</artifactId></dependency>
// after: add security so SecurityCheck gets registered
<dependency><groupId>io.quarkus</groupId><artifactId>quarkus-websockets-next</artifactId></dependency>
<dependency><groupId>io.quarkus</groupId><artifactId>quarkus-oidc</artifactId></dependency>

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the security extension is present whenever endpoint classes carry security annotations:
boolean hasSecurityAnnotations = endpointSources.stream()
    .anyMatch(src -> src.contains("@Authenticated") || src.contains("@AuthorizationPolicy"));
boolean hasSecurityExtension = pomIncludes("quarkus-security") || pomIncludes("quarkus-oidc");
if (hasSecurityAnnotations && !hasSecurityExtension) throw new IllegalStateException("Add a Quarkus security extension");

Prevention

Always add a security extension when using security annotations on endpoints
Keep quarkus-websockets-next and quarkus-security on the same BOM version
Verify the annotation is one processed by the installed security integration
Test endpoint builds in CI so missing wiring fails fast

When it happens

Trigger: An endpoint class carries a security annotation (detected by securityTransformer.hasSecurityAnnotation) while storage.getSecurityCheck(beanClassName) returns null during the build of a websockets-next application.

Common situations: Using @Authenticated or similar annotations without the quarkus-security/HTTP security extension on the classpath; annotation processed by a different (older) security integration; version drift between quarkus-websockets-next and quarkus-security after an upgrade.

Related errors

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