{"record":{"id":"74eb48fc6d61c036","repo":"apache/shenyu","slug":"failed-to-register-serverendpointconfig","errorCode":null,"errorMessage":"Failed to register ServerEndpointConfig: ","messagePattern":"Failed to register ServerEndpointConfig: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"shenyu-client/shenyu-client-websocket/shenyu-client-spring-websocket/src/main/java/org/apache/shenyu/client/spring/websocket/init/ShenyuServerEndpointerExporter.java","lineNumber":112,"sourceCode":"                .decoders(Arrays.asList(annotation.decoders()))\n                .encoders(Arrays.asList(annotation.encoders()))\n                .subprotocols(Arrays.asList(annotation.subprotocols()))\n                .configurator(configurator).build();\n        this.registerEndpoint(sec);\n    }\n\n    private void registerEndpoint(final ServerEndpointConfig endpointConfig) {\n        ServerContainer serverContainer = this.getServerContainer();\n        Assert.state(Objects.nonNull(serverContainer), \"No ServerContainer set\");\n\n        try {\n            if (this.logger.isDebugEnabled()) {\n                this.logger.debug(\"Registering ServerEndpointConfig: \" + endpointConfig);\n            }\n\n            serverContainer.addEndpoint(endpointConfig);\n        } catch (DeploymentException ex) {\n            throw new IllegalStateException(\"Failed to register ServerEndpointConfig: \" + endpointConfig, ex);\n        }\n    }\n}\n","sourceCodeStart":94,"sourceCodeEnd":116,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-client/shenyu-client-websocket/shenyu-client-spring-websocket/src/main/java/org/apache/shenyu/client/spring/websocket/init/ShenyuServerEndpointerExporter.java#L94-L116","documentation":"After building a ServerEndpointConfig, the exporter calls serverContainer.addEndpoint(); if the servlet container rejects the deployment it throws DeploymentException, which is wrapped in an IllegalStateException naming the failed endpoint config. This usually means the endpoint path is invalid, already registered, or the ServerContainer is not yet available/initialized.","triggerScenarios":"registerEndpoint() calls serverContainer.addEndpoint(endpointConfig) and the container raises DeploymentException — duplicate endpoint paths, malformed path values, or registering during a lifecycle phase when the websocket container is already deployed/locked.","commonSituations":"Two endpoint beans annotated with the same @ShenyuServerEndpoint value; invalid characters in the endpoint path; hot-reload/devtools restarts that re-register endpoints against a deployed container.","solutions":["Check the wrapped DeploymentException cause for the container's exact reason (duplicate path is the most common).","Ensure each @ShenyuServerEndpoint value is unique across all endpoint beans.","Use valid URI path values (leading '/', no illegal characters).","Avoid re-registering endpoints after container deployment — disable devtools hot restarts or guard registration idempotently."],"exampleFix":"// before\n@ShenyuServerEndpoint(\"/ws/echo\") public class EchoA {}\n@ShenyuServerEndpoint(\"/ws/echo\") public class EchoB {}\n// after\n@ShenyuServerEndpoint(\"/ws/echo\") public class EchoA {}\n@ShenyuServerEndpoint(\"/ws/echo2\") public class EchoB {}","handlingStrategy":"try-catch","validationCode":"String path = annotation.value();\nif (path == null || !path.startsWith(\"/\")) {\n    throw new IllegalArgumentException(\"invalid endpoint path: \" + path);\n}\n// ensure uniqueness across registered endpoints before addEndpoint\nSet<String> seen = new HashSet<>();\nif (!seen.add(path)) {\n    throw new IllegalArgumentException(\"duplicate endpoint path: \" + path);\n}","typeGuard":null,"tryCatchPattern":"try {\n    exporter.registerEndpoint(pojo);\n} catch (IllegalStateException e) {\n    LOG.error(\"Failed to deploy endpoint {}: {}\", pojo, e.getCause().getMessage(), e);\n}","preventionTips":["Keep @ShenyuServerEndpoint values unique across the application.","Register endpoints during container startup, never after deployment completes.","Always inspect the DeploymentException cause; it names the real container-side reason."],"tags":["websocket","deployment","servlet-container"],"backgroundTag":"module-init-failed","analyzedSha":"567142e07261b3e615ae8850b30f4421f455cc5d","analyzedAt":"2026-09-12T10:08:21.293Z","contentChangedAt":"2026-09-12T10:08:21.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}