{"record":{"id":"22a8530cdcd6476b","repo":"quarkusio/quarkus","slug":"unknown-websocket-subprotocol","errorCode":null,"errorMessage":"Unknown websocket subprotocol: ","messagePattern":"Unknown websocket subprotocol: ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/smallrye-graphql/deployment/src/main/java/io/quarkus/smallrye/graphql/deployment/SmallRyeGraphQLProcessor.java","lineNumber":943,"sourceCode":"        }\n\n        boolean runBlocking = shouldRunBlockingRoute(graphQLConfig);\n\n        // Subscriptions\n        Handler<RoutingContext> graphqlOverWebsocketHandler = recorder\n                .graphqlOverWebsocketHandler(beanContainer.getValue(), graphQLInitializedBuildItem.getInitialized(),\n                        runBlocking);\n\n        HttpRootPathBuildItem.Builder subscriptionsBuilder = httpRootPathBuildItem.routeBuilder()\n                .orderedRoute(graphQLConfig.rootPath(), GRAPHQL_WEBSOCKET_HANDLER_ORDER)\n                .handler(graphqlOverWebsocketHandler);\n        routeProducer.produce(subscriptionsBuilder.build());\n\n        // WebSocket subprotocols\n        graphQLConfig.websocketSubprotocols().ifPresentOrElse(subprotocols -> {\n            for (String subprotocol : subprotocols) {\n                if (!SUPPORTED_WEBSOCKET_SUBPROTOCOLS.contains(subprotocol)) {\n                    throw new IllegalArgumentException(\"Unknown websocket subprotocol: \" + subprotocol);\n                } else {\n                    webSocketSubProtocols.produce(new WebsocketSubProtocolsBuildItem(subprotocol));\n                }\n            }\n        }, () -> {\n            // if unspecified, allow all supported subprotocols\n            for (String subprotocol : SUPPORTED_WEBSOCKET_SUBPROTOCOLS) {\n                webSocketSubProtocols.produce(new WebsocketSubProtocolsBuildItem(subprotocol));\n            }\n        });\n\n        // Queries and Mutations\n        boolean allowCompression = httpBuildTimeConfig.enableCompression() && httpBuildTimeConfig.compressMediaTypes()\n                .map(mediaTypes -> mediaTypes.contains(GRAPHQL_MEDIA_TYPE))\n                .orElse(false);\n        Handler<RoutingContext> executionHandler = recorder.executionHandler(graphQLInitializedBuildItem.getInitialized(),\n                runBlocking, allowCompression);\n","sourceCodeStart":925,"sourceCodeEnd":961,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/smallrye-graphql/deployment/src/main/java/io/quarkus/smallrye/graphql/deployment/SmallRyeGraphQLProcessor.java#L925-L961","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use only supported values: graphql-ws or graphql-transport-ws (check the docs of your Quarkus version for the exact list)","Remove the property entirely — by default all supported subprotocols are allowed","Fix casing/spelling of the configured value(s) in application.properties","If a newer protocol is needed, upgrade Quarkus to a version whose SUPPORTED_WEBSOCKET_SUBPROTOCOLS includes it"],"exampleFix":"// before\nquarkus.smallrye-graphql.websocket.subprotocols=subscriptions-transport-ws\n// after\nquarkus.smallrye-graphql.websocket.subprotocols=graphql-ws,graphql-transport-ws","handlingStrategy":"validation","validationCode":"// Validate configured subprotocols against the supported set before build\nSet<String> SUPPORTED = Set.of(\"graphql-ws\", \"graphql-transport-ws\");\nString[] configured = System.getProperty(\"quarkus.smallrye-graphql.websocket.subprotocols\", \"\")\n    .split(\",\");\nfor (String p : configured) {\n    if (!p.isBlank() && !SUPPORTED.contains(p.trim())) {\n        throw new IllegalArgumentException(\"Unknown websocket subprotocol: \" + p.trim()\n            + \". Supported: \" + SUPPORTED);\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use documented values: graphql-ws, graphql-transport-ws","Omit the property to accept all supported subprotocols","Check the supported list for your Quarkus version before copying config from tutorials","Upgrade Quarkus if you need a newer subprotocol"],"tags":["graphql","websocket","configuration","subscriptions"],"backgroundTag":"invalid-config-value","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}