quarkusio/quarkus · error · IllegalArgumentException

[%s] is not a valid path parameter in the path %s

Error message

[%s] is not a valid path parameter in the path %s

What it means

WebSocketConnectorBase.pathParam(String,String) only accepts parameter names that were declared as {placeholders} in the endpoint's @WebSocketClient path. If the name is not among the declared pathParamNames, this IllegalArgumentException is thrown, preventing silent mismatches between declared and supplied parameters.

Source

Thrown at extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/WebSocketConnectorBase.java:125

    }

    public THIS addHeader(String name, String value) {
        Objects.requireNonNull(name);
        Objects.requireNonNull(value);
        List<String> values = headers.get(name);
        if (values == null) {
            values = new ArrayList<>();
            headers.put(name, values);
        }
        values.add(value);
        return self();
    }

    public THIS pathParam(String name, String value) {
        Objects.requireNonNull(name);
        Objects.requireNonNull(value);
        if (!pathParamNames.contains(name)) {
            throw new IllegalArgumentException(
                    String.format("[%s] is not a valid path parameter in the path %s", name, path));
        }
        pathParams.put(name, value);
        return self();
    }

    public THIS addSubprotocol(String value) {
        subprotocols.add(Objects.requireNonNull(value));
        return self();
    }

    public <VALUE> THIS userData(TypedKey<VALUE> key, VALUE value) {
        userData.put(key.value(), value);
        return self();
    }

    void setPath(String path) {
        this.path = Objects.requireNonNull(path);

View on GitHub (pinned to e1c734241f)

Solutions

1. Make the name passed to pathParam() match a {name} placeholder in the endpoint's path annotation exactly
2. Check the @WebSocketClient path for typos or renamed placeholders
3. Remove the pathParam() call if the path has no such placeholder

Example fix

// before
@WebSocketClient(path = "/chat/{roomId}")
connector.pathParam("roomID", "42");
// after
connector.pathParam("roomId", "42");

boolean isValidParam = endpointPath.contains("{" + name + "}");
if (!isValidParam) throw new IllegalArgumentException(name + " not declared in path");

try {
    connector.pathParam(name, value);
} catch (IllegalArgumentException e) {
    log.error("Path param {} not declared in endpoint path", name, e);
}

When it happens

Trigger: Calling connector.pathParam("id", value) where "id" does not appear as {id} in the @WebSocketClient(path = ...) annotation — including typos, case mismatches, or passing a param for an endpoint whose path has no placeholders.

Common situations: Renaming the path in the annotation without updating connector code; copy-pasted connector code referencing another endpoint's parameter; typo in the parameter name string.

Related errors

• [%s] is not a valid scheme in the base URI %s
• Unable to obtain the path param for:
• Invalid status code:
• Endpoint URI not set!
• Unable to obtain the config value for:

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