quarkusio/quarkus · error · WebSocketException

@PathParam name [%s] must be used in the endpoint path [%s]:

Error message

@PathParam name [%s] must be used in the endpoint path [%s]: %s

What it means

Quarkus websockets-next throws this during build-time validation when a callback method parameter annotated with @PathParam declares a name that does not appear as a path segment variable in the endpoint's @WebSocket/@WebSocketClient path. The path parameter would never be populated, so the deployment is rejected early. It only applies to endpoints with a path; global error handlers with @PathParam are rejected separately.

Source

Thrown at extensions/websockets-next/deployment/src/main/java/io/quarkus/websockets/next/deployment/PathParamCallbackArgument.java:33

import io.quarkus.websockets.next.runtime.WebSocketConnectionBase;

class PathParamCallbackArgument implements CallbackArgument {

    @Override
    public boolean matches(ParameterContext context) {
        String name = getParamName(context);
        if (name != null) {
            if (!context.parameter().type().name().equals(WebSocketDotNames.STRING)) {
                throw new WebSocketException("Method parameter annotated with @PathParam must be java.lang.String: "
                        + WebSocketProcessor.methodToString(context.parameter().method()));
            }
            if (context.endpointPath() == null) {
                throw new WebSocketException("Global error handlers may not accept @PathParam parameters: "
                        + WebSocketProcessor.methodToString(context.parameter().method()));
            }
            List<String> pathParams = getPathParamNames(context.endpointPath());
            if (!pathParams.contains(name)) {
                throw new WebSocketException(
                        String.format(
                                "@PathParam name [%s] must be used in the endpoint path [%s]: %s", name,
                                context.endpointPath(),
                                WebSocketProcessor.methodToString(context.parameter().method())));
            }
            return true;
        }
        return false;
    }

    @Override
    public Expr get(InvocationBytecodeContext context) {
        String paramName = getParamName(context);
        return context.bytecode().invokeVirtual(
                MethodDesc.of(WebSocketConnectionBase.class, "pathParam", String.class, String.class),
                context.getConnection(), Const.of(paramName));
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Make the @PathParam value exactly match a {name} segment in the endpoint path
2. Or remove the segment rename mismatch: change the path (e.g. @WebSocket(path="/chat/{roomId}")) so it contains the parameter name
3. Or remove the @PathParam parameter if it is not needed
4. Verify the class is compiled with -parameters if relying on parameter names instead of explicit values

Example fix

// before
@WebSocket(path = "/ws/chat")
@OnOpen void open(@PathParam String roomId) {}
// after
@WebSocket(path = "/ws/chat/{roomId}")
@OnOpen void open(@PathParam String roomId) {}

// Before building, assert every @PathParam name appears in the path template
static void checkPathParams(String path, String... pathParamNames) {
  for (String p : pathParamNames) {
    if (!path.contains("{" + p + "}"))
      throw new IllegalStateException("@PathParam '" + p + "' missing from path " + path);
  }
}
// checkPathParams("/ws/chat/{roomId}", "roomId");

When it happens

Trigger: Annotating a callback parameter with @PathParam("id") (or bare @PathParam relying on -parameters names) on @OnOpen/@OnTextMessage/@OnMessage/@OnError methods while the endpoint path, e.g. @WebSocket(path="/ws/{endpoint}"), contains no matching {id} segment.

Common situations: Renaming a path variable in the endpoint path without updating the @PathParam value; copying a handler from another endpoint with different path variables; typos like {userId} vs @PathParam("user"); adding @PathParam to a global error handler whose endpointPath is null.

Related errors

• Unable to extract the path parameter name - method parameter
• Endpoint class may not be annotated with both @WebSocket and
• Failed to open path tree with root %s
• Dev services for ${request.getName()} requires a startable s
• Name cannot start with '/':${name}

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