quarkusio/quarkus · error · IllegalArgumentException

Unknown websocket subprotocol:

Error message

Unknown websocket subprotocol: 

What it means

SmallRyeGraphQLProcessor validates the configured WebSocket subprotocols for GraphQL subscriptions against a fixed whitelist (SUPPORTED_WEBSOCKET_SUBPROTOCOLS, e.g. graphql-ws and graphql-transport-ws). An unsupported value in quarkus.smallrye-graphql.websocket.subprotocols causes IllegalArgumentException 'Unknown websocket subprotocol: <value>' at build time.

Source

Thrown at extensions/smallrye-graphql/deployment/src/main/java/io/quarkus/smallrye/graphql/deployment/SmallRyeGraphQLProcessor.java:943

        }

        boolean runBlocking = shouldRunBlockingRoute(graphQLConfig);

        // Subscriptions
        Handler<RoutingContext> graphqlOverWebsocketHandler = recorder
                .graphqlOverWebsocketHandler(beanContainer.getValue(), graphQLInitializedBuildItem.getInitialized(),
                        runBlocking);

        HttpRootPathBuildItem.Builder subscriptionsBuilder = httpRootPathBuildItem.routeBuilder()
                .orderedRoute(graphQLConfig.rootPath(), GRAPHQL_WEBSOCKET_HANDLER_ORDER)
                .handler(graphqlOverWebsocketHandler);
        routeProducer.produce(subscriptionsBuilder.build());

        // WebSocket subprotocols
        graphQLConfig.websocketSubprotocols().ifPresentOrElse(subprotocols -> {
            for (String subprotocol : subprotocols) {
                if (!SUPPORTED_WEBSOCKET_SUBPROTOCOLS.contains(subprotocol)) {
                    throw new IllegalArgumentException("Unknown websocket subprotocol: " + subprotocol);
                } else {
                    webSocketSubProtocols.produce(new WebsocketSubProtocolsBuildItem(subprotocol));
                }
            }
        }, () -> {
            // if unspecified, allow all supported subprotocols
            for (String subprotocol : SUPPORTED_WEBSOCKET_SUBPROTOCOLS) {
                webSocketSubProtocols.produce(new WebsocketSubProtocolsBuildItem(subprotocol));
            }
        });

        // Queries and Mutations
        boolean allowCompression = httpBuildTimeConfig.enableCompression() && httpBuildTimeConfig.compressMediaTypes()
                .map(mediaTypes -> mediaTypes.contains(GRAPHQL_MEDIA_TYPE))
                .orElse(false);
        Handler<RoutingContext> executionHandler = recorder.executionHandler(graphQLInitializedBuildItem.getInitialized(),
                runBlocking, allowCompression);

View on GitHub (pinned to e1c734241f)

Solutions

1. Use only supported values: graphql-ws or graphql-transport-ws (check the docs of your Quarkus version for the exact list)
2. Remove the property entirely — by default all supported subprotocols are allowed
3. Fix casing/spelling of the configured value(s) in application.properties
4. If a newer protocol is needed, upgrade Quarkus to a version whose SUPPORTED_WEBSOCKET_SUBPROTOCOLS includes it

Example fix

// before
quarkus.smallrye-graphql.websocket.subprotocols=subscriptions-transport-ws
// after
quarkus.smallrye-graphql.websocket.subprotocols=graphql-ws,graphql-transport-ws

// Validate configured subprotocols against the supported set before build
Set<String> SUPPORTED = Set.of("graphql-ws", "graphql-transport-ws");
String[] configured = System.getProperty("quarkus.smallrye-graphql.websocket.subprotocols", "")
    .split(",");
for (String p : configured) {
    if (!p.isBlank() && !SUPPORTED.contains(p.trim())) {
        throw new IllegalArgumentException("Unknown websocket subprotocol: " + p.trim()
            + ". Supported: " + SUPPORTED);
    }
}

When it happens

Trigger: Setting quarkus.smallrye-graphql.websocket.subprotocols in application.properties with a value outside the supported set — e.g. a typo (graphql_ws), legacy names (subscriptions-transport-ws), or a new protocol not supported by the bundled Quarkus version.

Common situations: Copying configuration from an Apollo/subscriptions-transport-ws tutorial; upgrading from older examples using 'graphql-ws' vs 'graphql-transport-ws' interchangeably; multiple values where one is misspelled.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• quarkus.smallrye-graphql.root-path-ui was set to "/", this i
• quarkus.vertx-graphql.ui.path was set to "<path>", this is n
• Failed to load application configuration
• Failed to initialize application configuration
• Unrecognized option for quarkus.bootstrap.misaligned-platfor

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