quarkusio/quarkus · error · WebSocketException

Unable to extract the path parameter name - method parameter

Error message

Unable to extract the path parameter name - method parameter names not recorded for %s: compile the class with -parameters

What it means

Quarkus websockets-next needs a @PathParam parameter's name, but neither an explicit value was given on the annotation nor could the name be inferred because the class was compiled without the -parameters flag. The build fails so the path parameter is never silently left unbound.

Source

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

        String paramName = getParamName(context);
        return context.bytecode().invokeVirtual(
                MethodDesc.of(WebSocketConnectionBase.class, "pathParam", String.class, String.class),
                context.getConnection(), Const.of(paramName));
    }

    private String getParamName(ParameterContext context) {
        AnnotationInstance pathParamAnnotation = Annotations.find(context.parameterAnnotations(), WebSocketDotNames.PATH_PARAM);
        if (pathParamAnnotation != null) {
            String name;
            AnnotationValue nameVal = pathParamAnnotation.value();
            if (nameVal != null) {
                name = nameVal.asString();
            } else {
                // Try to use the element name
                name = context.parameter().name();
            }
            if (name == null) {
                throw new WebSocketException(String.format(
                        "Unable to extract the path parameter name - method parameter names not recorded for %s: compile the class with -parameters",
                        context.parameter().method().declaringClass().name()));
            }
            return name;
        }
        return null;
    }

    static List<String> getPathParamNames(String path) {
        List<String> names = new ArrayList<>();
        Matcher m = WebSocketProcessor.TRANSLATED_PATH_PARAM_PATTERN.matcher(path);
        while (m.find()) {
            names.add(m.group().substring(1));
        }
        return names;
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the -parameters flag to the compiler configuration (maven-compiler-plugin <parameters>true</parameters> or Gradle compileJava { options.compilerArgs << '-parameters' })
2. Or specify the name explicitly: @PathParam("roomId") instead of bare @PathParam
3. Recompile the endpoint class after fixing compiler settings

Example fix

// before
<artifactId>maven-compiler-plugin</artifactId> <!-- no -parameters -->
// after
<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration><parameters>true</parameters></configuration>
</plugin>

// build.gradle.kts — ensure parameter names are recorded
tasks.compileJava { options.compilerArgs.add("-parameters") }
// or Maven: <parameters>true</parameters> in maven-compiler-plugin

When it happens

Trigger: Using bare @PathParam without a value on a callback method parameter in a class compiled without -parameters (e.g. default javac/maven config lacking <compilerArgs>-parameters</compilerArgs>, or an unannotated third-party endpoint class added to the archive).

Common situations: New Maven/Gradle projects missing the -parameters compiler argument (common when overriding maven-compiler-plugin config); IDE-compiled classes lacking parameter name info; libraries shipping precompiled websocket endpoints.

Related errors

• @PathParam name [%s] must be used in the endpoint path [%s]:
• Multiple global @OnError callbacks may not accept the same e
• Endpoint class may not be annotated with both @WebSocket and
• Multiple endpoints [%s, %s] define the same path: %s
• Multiple endpoints [%s, %s] define the same endpoint id: %s

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