quarkusio/quarkus · error · WebSocketServerException

Multiple client endpoints [%s, %s] define the same path: %s

Error message

Multiple client endpoints [%s, %s] define the same path: %s

What it means

Analogous to server endpoints, client endpoints (@WebSocketClient) register their paths in a build-time map; duplicate client paths are ambiguous for connection creation and raise WebSocketServerException at deployment.

Source

Thrown at extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/WebSocketProcessor.java:382

                AnnotationValue endpointIdValue = webSocketAnnotation.value("endpointId");
                if (endpointIdValue == null) {
                    id = beanClass.name().toString();
                } else {
                    id = endpointIdValue.asString();
                }
                DotName prevId = serverIdToEndpoint.put(id, beanClass.name());
                if (prevId != null) {
                    throw new WebSocketServerException(
                            String.format("Multiple endpoints [%s, %s] define the same endpoint id: %s", prevId, beanClass,
                                    id));
                }
                inboundProcessingMode = webSocketAnnotation.value("inboundProcessingMode");
            } else {
                target = Target.CLIENT;
                path = getPath(webSocketClientAnnotation.value("path").asString());
                DotName prevPath = clientPathToEndpoint.put(path, beanClass.name());
                if (prevPath != null) {
                    throw new WebSocketServerException(
                            String.format("Multiple client endpoints [%s, %s] define the same path: %s", prevPath, beanClass,
                                    path));
                }
                AnnotationValue clientIdValue = webSocketClientAnnotation.value("clientId");
                if (clientIdValue == null) {
                    id = beanClass.name().toString();
                } else {
                    id = clientIdValue.asString();
                }
                DotName prevId = clientIdToEndpoint.put(id, beanClass.name());
                if (prevId != null) {
                    throw new WebSocketServerException(
                            String.format("Multiple client endpoints [%s, %s] define the same endpoint id: %s", prevId,
                                    beanClass,
                                    id));
                }
                inboundProcessingMode = webSocketClientAnnotation.value("inboundProcessingMode");
            }

View on GitHub (pinned to e1c734241f)

Solutions

1. Give each @WebSocketClient a distinct path value
2. If both clients intentionally target the same server path, differentiate them with path expressions/properties, e.g. path = "${client.a.path}" and "${client.b.path}"
3. Remove one of the duplicate client endpoints

Example fix

// before
@WebSocketClient(path = "ws://host/ws") class C1 {}
@WebSocketClient(path = "ws://host/ws") class C2 {}
// after
@WebSocketClient(path = "ws://host/ws") class C1 {}
@WebSocketClient(path = "ws://host/ws2") class C2 {}

@Test
void clientPathsUnique() {
  Set<String> paths = new HashSet<>();
  for (Class<?> c : allClients) {
    if (!paths.add(c.getAnnotation(WebSocketClient.class).path()))
      throw new AssertionError("Duplicate client path");
  }
}

When it happens

Trigger: Two @WebSocketClient classes with the same path attribute value, e.g. both "ws://localhost:8080/ws" or the same relative path template.

Common situations: Copy-pasting a client class without changing its path; multiple clients targeting the same server endpoint intentionally but declared identically.

Related errors

• Multiple endpoints [%s, %s] define the same path: %s
• Multiple client endpoints [%s, %s] define the same endpoint
• @PathParam name [%s] must be used in the endpoint path [%s]:
• Unable to extract the path parameter name - method parameter
• Multiple global @OnError callbacks may not accept the same e

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/1fc5eb1c7e3be88d. Report an issue: GitHub.