apache/shenyu · error · IllegalStateException

Failed to register ServerEndpointConfig:

Error message

Failed to register ServerEndpointConfig: 

What it means

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.

Solutions

1. Check the wrapped DeploymentException cause for the container's exact reason (duplicate path is the most common).
2. Ensure each @ShenyuServerEndpoint value is unique across all endpoint beans.
3. Use valid URI path values (leading '/', no illegal characters).
4. Avoid re-registering endpoints after container deployment — disable devtools hot restarts or guard registration idempotently.

Example fix

// before
@ShenyuServerEndpoint("/ws/echo") public class EchoA {}
@ShenyuServerEndpoint("/ws/echo") public class EchoB {}
// after
@ShenyuServerEndpoint("/ws/echo") public class EchoA {}
@ShenyuServerEndpoint("/ws/echo2") public class EchoB {}

String path = annotation.value();
if (path == null || !path.startsWith("/")) {
    throw new IllegalArgumentException("invalid endpoint path: " + path);
}
// ensure uniqueness across registered endpoints before addEndpoint
Set<String> seen = new HashSet<>();
if (!seen.add(path)) {
    throw new IllegalArgumentException("duplicate endpoint path: " + path);
}

try {
    exporter.registerEndpoint(pojo);
} catch (IllegalStateException e) {
    LOG.error("Failed to deploy endpoint {}: {}", pojo, e.getCause().getMessage(), e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• websocket on client open failed, namespaceId is null
• namespaceId can not be null
• websocket sync token is not configured
• websocket sync token is invalid
• Class missing annotation ShenyuServerEndpoint! class name:

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/74eb48fc6d61c036. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-client/shenyu-client-websocket/shenyu-client-spring-websocket/src/main/java/org/apache/shenyu/client/spring/websocket/init/ShenyuServerEndpointerExporter.java:112

                .decoders(Arrays.asList(annotation.decoders()))
                .encoders(Arrays.asList(annotation.encoders()))
                .subprotocols(Arrays.asList(annotation.subprotocols()))
                .configurator(configurator).build();
        this.registerEndpoint(sec);
    }

    private void registerEndpoint(final ServerEndpointConfig endpointConfig) {
        ServerContainer serverContainer = this.getServerContainer();
        Assert.state(Objects.nonNull(serverContainer), "No ServerContainer set");

        try {
            if (this.logger.isDebugEnabled()) {
                this.logger.debug("Registering ServerEndpointConfig: " + endpointConfig);
            }

            serverContainer.addEndpoint(endpointConfig);
        } catch (DeploymentException ex) {
            throw new IllegalStateException("Failed to register ServerEndpointConfig: " + endpointConfig, ex);
        }
    }
}

View on GitHub (pinned to 567142e072)