{"record":{"id":"6beb272b15d4efc3","repo":"quarkusio/quarkus","slug":"unable-to-create-endpoint-instance","errorCode":null,"errorMessage":"Unable to create endpoint instance: ","messagePattern":"Unable to create endpoint instance: ","errorType":"exception","errorClass":"WebSocketException","httpStatus":null,"severity":"error","filePath":"extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/Endpoints.java","lineNumber":453,"sourceCode":"            if (cl == null) {\n                cl = WebSocketServerRecorder.class.getClassLoader();\n            }\n            @SuppressWarnings(\"unchecked\")\n            Class<? extends WebSocketEndpoint> endpointClazz = (Class<? extends WebSocketEndpoint>) cl\n                    .loadClass(endpointClassName);\n\n            ErrorInterceptor errorInterceptor = telemetrySupport == null ? null : telemetrySupport.getErrorInterceptor();\n            WebSocketEndpoint endpoint = (WebSocketEndpoint) endpointClazz\n                    .getDeclaredConstructor(WebSocketConnectionBase.class, Codecs.class, ContextSupport.class,\n                            SecuritySupport.class, ErrorInterceptor.class)\n                    .newInstance(connection, codecs, contextSupport, securitySupport, errorInterceptor);\n            if (telemetrySupport != null) {\n                return telemetrySupport.decorate(endpoint, connection);\n            }\n\n            return endpoint;\n        } catch (Exception e) {\n            throw new WebSocketException(\"Unable to create endpoint instance: \" + endpointClassName, e);\n        }\n    }\n\n}\n","sourceCodeStart":435,"sourceCodeEnd":458,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/Endpoints.java#L435-L458","documentation":"When a client connects to a server endpoint, WebSockets Next must instantiate the endpoint bean class reflectively (via the container). Endpoints.createEndpoint catches any Exception during instantiation/wiring and rethrows it as WebSocketException 'Unable to create endpoint instance: <className>', preserving the cause.","triggerScenarios":"The endpoint bean cannot be created at connection time — CDI bean lookup/instantiation fails, a constructor throws, a dependent bean dependency is unsatisfied, the class failed to initialize, or the bean scope prohibits creation in the current context.","commonSituations":"Endpoint class depends on a bean not available at connection time; an @PostConstruct throws; wrong bean scope (e.g. @Singleton with unsatisfied dependency); native-image missing reflection config for a manually registered class.","solutions":["Inspect the wrapped cause 'Caused by' to find the root failure and fix it","Verify all beans injected into the endpoint are available and their scopes permit creation","Ensure @PostConstruct logic cannot throw in the target environment (e.g. missing config properties)","For native builds, confirm the endpoint is discovered via annotation rather than manual reflection registration"],"exampleFix":"// before\nclass Sock {\n    @Inject MissingBean bean; // unsatisfied -> instantiation fails\n}\n// after\n@ApplicationScoped\nclass MissingBean { }\nclass Sock {\n    @Inject MissingBean bean; // now resolvable\n}","handlingStrategy":"try-catch","validationCode":"// verify endpoint dependencies are satisfied before accepting connections\nvoid checkEndpoint(Class<?> endpoint) {\n    Instance<?> inst = Arc.container().select(endpoint);\n    if (!inst.isResolvable())\n        throw new IllegalStateException(\"Endpoint bean not resolvable: \" + endpoint);\n}","typeGuard":null,"tryCatchPattern":"try {\n    connection = client.connect().await().indefinitely();\n} catch (WebSocketException e) {\n    if (e.getMessage().startsWith(\"Unable to create endpoint instance\")) {\n        log.error(\"Endpoint wiring failed\", e.getCause()); // inspect cause\n    }\n}","preventionTips":["Check 'Caused by' when this error surfaces — the root failure is wrapped","Verify all injected beans and @PostConstruct logic cannot fail at connection time"],"tags":["cdi","websockets","instantiation"],"backgroundTag":"bean-creation-failed","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"}