{"record":{"id":"8a95ca161ab48a64","repo":"perwendel/spark","slug":"could-not-instantiate-websocket-handler","errorCode":null,"errorMessage":"Could not instantiate websocket handler","messagePattern":"Could not instantiate websocket handler","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/main/java/spark/embeddedserver/jetty/websocket/WebSocketHandlerClassWrapper.java","lineNumber":19,"sourceCode":"package spark.embeddedserver.jetty.websocket;\n\nimport static java.util.Objects.requireNonNull;\n\npublic class WebSocketHandlerClassWrapper implements WebSocketHandlerWrapper {\n    \n    private final Class<?> handlerClass;\n\n    public WebSocketHandlerClassWrapper(Class<?> handlerClass) {\n        requireNonNull(handlerClass, \"WebSocket handler class cannot be null\");\n        WebSocketHandlerWrapper.validateHandlerClass(handlerClass);\n        this.handlerClass = handlerClass;\n    }\n    @Override\n    public Object getHandler() {\n        try {\n            return handlerClass.newInstance();\n        } catch (InstantiationException | IllegalAccessException ex) {\n            throw new RuntimeException(\"Could not instantiate websocket handler\", ex);\n        }\n    }\n\n}\n","sourceCodeStart":1,"sourceCodeEnd":24,"githubUrl":"https://github.com/perwendel/spark/blob/1973e402f5d4c1442ad34a1d38ed0758079f7773/src/main/java/spark/embeddedserver/jetty/websocket/WebSocketHandlerClassWrapper.java#L1-L24","documentation":"WebSocketHandlerClassWrapper wraps a WebSocket handler specified as a Class and instantiates it in getHandler() via handlerClass.newInstance(). If the class cannot be instantiated — it is abstract, an interface, or has no accessible no-arg constructor — the reflective instantiation throws InstantiationException/IllegalAccessException, rethrown as RuntimeException('Could not instantiate websocket handler').","triggerScenarios":"Registering a WebSocket handler class that is abstract or an interface via Spark.webSocket(\"/path\", HandlerClass.class), or one without a public no-arg constructor.","commonSituations":"Passing a handler class with constructor dependencies (DI-style classes); abstract handler base classes; non-static inner classes whose constructor requires the outer instance.","solutions":["Make the handler class concrete, non-abstract, with a public no-arg constructor.","Use the WebSocketHandler instance variant (Spark.webSocket(\"/path\", handler)) so Spark doesn't reflectively instantiate the class.","If the handler needs dependencies, wrap a pre-built instance in a WebSocketHandlerWrapper instead of passing the class.","Ensure inner handler classes are static (or top-level) so newInstance() can construct them."],"exampleFix":"// before\npublic abstract class WsHandler implements WebSocketHandler { }\nSpark.webSocket(\"/ws\", WsHandler.class); // newInstance fails\n// after\npublic class WsHandler implements WebSocketHandler {\n    public WsHandler() { }\n    public void onOpen(WebSocket ws) { }\n}\nSpark.webSocket(\"/ws\", WsHandler.class);","handlingStrategy":"validation","validationCode":"Class<?> c = WsHandler.class;\nif (c.isInterface() || java.lang.reflect.Modifier.isAbstract(c.getModifiers())) {\n    throw new IllegalArgumentException(\"Handler must be a concrete class\");\n}\ntry { c.getDeclaredConstructor().setAccessible(true); } catch (NoSuchMethodException e) {\n    throw new IllegalArgumentException(\"Handler needs a no-arg constructor\");\n}\nSpark.webSocket(\"/ws\", WsHandler.class);","typeGuard":"boolean instantiableHandler(Class<?> c) {\n    return !c.isInterface() && !java.lang.reflect.Modifier.isAbstract(c.getModifiers());\n}","tryCatchPattern":"try {\n    Spark.webSocket(\"/ws\", WsHandler.class);\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"Could not instantiate websocket handler\")) {\n        LOG.error(\"Handler class must be concrete with a no-arg constructor\", e);\n    } else { throw e; }\n}","preventionTips":["Make WebSocket handler classes public, concrete, with public no-arg constructors.","Avoid DI-constructed handler classes; pass dependencies via static config or instance wrappers.","Add a unit test that calls newInstance() on every registered handler class."],"tags":["java","websocket","reflection"],"backgroundTag":"class-not-found","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"}