{"record":{"id":"7f8f72522f4fa0e7","repo":"perwendel/spark","slug":"websockets-are-only-supported-in-the-embedded-serv","errorCode":null,"errorMessage":"WebSockets are only supported in the embedded server","messagePattern":"WebSockets are only supported in the embedded server","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/main/java/spark/Service.java","lineNumber":427,"sourceCode":"\n    /**\n     * Maps the given path to the given WebSocket handler instance.\n     * <p>\n     * This is currently only available in the embedded server mode.\n     *\n     * @param path    the WebSocket path.\n     * @param handler the handler instance that will manage the WebSocket connection to the given path.\n     */\n    public void webSocket(String path, Object handler) {\n        addWebSocketHandler(path, new WebSocketHandlerInstanceWrapper(handler));\n    }\n\n    private synchronized void addWebSocketHandler(String path, WebSocketHandlerWrapper handlerWrapper) {\n        if (initialized) {\n            throwBeforeRouteMappingException();\n        }\n        if (isRunningFromServlet()) {\n            throw new IllegalStateException(\"WebSockets are only supported in the embedded server\");\n        }\n        requireNonNull(path, \"WebSocket path cannot be null\");\n        if (webSocketHandlers == null) {\n            webSocketHandlers = new HashMap<>();\n        }\n\n        webSocketHandlers.put(path, handlerWrapper);\n    }\n\n    /**\n     * Sets the max idle timeout in milliseconds for WebSocket connections.\n     *\n     * @param timeoutMillis The max idle timeout in milliseconds.\n     * @return the object with max idle timeout set for WebSocket connections\n     */\n    public synchronized Service webSocketIdleTimeoutMillis(long timeoutMillis) {\n        if (initialized) {\n            throwBeforeRouteMappingException();","sourceCodeStart":409,"sourceCodeEnd":445,"githubUrl":"https://github.com/perwendel/spark/blob/1973e402f5d4c1442ad34a1d38ed0758079f7773/src/main/java/spark/Service.java#L409-L445","documentation":"WebSocket handlers in Spark are registered via webSocket(path, wrapper), which delegates to addWebSocketHandler. WebSockets require Spark's own embedded Jetty server; when Spark is running as a servlet inside an external container (isRunningFromServlet() is true) it cannot install its WebSocket support, so registration throws IllegalStateException.","triggerScenarios":"Calling webSocket(\"/ws\", handler) (or webSocketAnnotation) while the app is deployed as a WAR in an external servlet container such as Tomcat/WildFly, i.e. running with the spark-servlet bootstrap instead of the embedded server.","commonSituations":"Deploying a Spark app as a WAR to a corporate Tomcat instance and adding WebSocket endpoints; switching from embedded jetty (dev) to servlet deployment (prod) without removing WebSocket routes.","solutions":["Run the app with the embedded Spark server (main() with Spark.port/threadPool etc.) instead of deploying as a WAR.","Handle WebSockets with the servlet container's own native WebSocket support (javax.websocket endpoints) when servlet deployment is mandatory.","Remove or conditionally guard webSocket() registration when running in servlet mode."],"exampleFix":"// before\npublic class App extends SparkApplication { // deployed as WAR\n    public void init() { webSocket(\"/ws\", WsHandler.class); } // throws\n}\n// after\n// deploy with embedded server: run App.main() directly, or use container-native JSR-356 endpoints for /ws","handlingStrategy":"validation","validationCode":"if (!isEmbeddedMode()) { // e.g. you deploy as WAR\n    throw new IllegalStateException(\"Register WebSockets only in embedded mode\");\n}\nSpark.webSocket(\"/ws\", WsHandler.class);","typeGuard":null,"tryCatchPattern":"try {\n    Spark.webSocket(\"/ws\", WsHandler.class);\n} catch (IllegalStateException e) {\n    LOG.warn(\"WebSockets unavailable in servlet mode; using container-native endpoints\");\n}","preventionTips":["Know your deployment mode: WAR in Tomcat => no Spark WebSockets.","Centralize WebSocket registration in embedded-only bootstrap code.","Document in your deploy pipeline that WAR deployments need JSR-356 endpoints instead."],"tags":["java","websocket","servlet"],"backgroundTag":"operation-not-supported","analyzedSha":"1973e402f5d4c1442ad34a1d38ed0758079f7773","analyzedAt":"2026-09-10T14:38:22.866Z","contentChangedAt":"2026-09-10T14:38:22.866Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}