quarkusio/quarkus · error · IllegalArgumentException

Invalid status code:

Error message

Invalid status code: 

What it means

CloseReason validates WebSocket close status codes. RFC 6455/Quarkus restrict which codes may be used when closing (1000, 1001, 3000-4999, etc.); codes like 1004-1006 or out-of-range values are invalid. Passing such a code to the validating CloseReason constructor throws IllegalArgumentException 'Invalid status code: <code>'.

Source

Thrown at extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/CloseReason.java:30

 * @see WebSocketClientConnection#close(CloseReason)
 */
public class CloseReason {

    public static final CloseReason NORMAL = new CloseReason(WebSocketCloseStatus.NORMAL_CLOSURE.code());

    public static final CloseReason ABNORMAL = new CloseReason(WebSocketCloseStatus.ABNORMAL_CLOSURE.code(), null, false);

    public static final CloseReason EMPTY = new CloseReason(WebSocketCloseStatus.EMPTY.code(), null, false);

    public static final CloseReason INTERNAL_SERVER_ERROR = new CloseReason(WebSocketCloseStatus.INTERNAL_SERVER_ERROR.code());

    private final int code;

    private final String message;

    private CloseReason(int code, String message, boolean validate) {
        if (validate && !WebSocketCloseStatus.isValidStatusCode(code)) {
            throw new IllegalArgumentException("Invalid status code: " + code);
        }
        this.code = code;
        this.message = message;
    }

    /**
     *
     * @param code The status code must comply with RFC-6455
     */
    public CloseReason(int code) {
        this(code, null, true);
    }

    /**
     *
     * @param code The status code must comply with RFC-6455
     * @param message
     */

View on GitHub (pinned to e1c734241f)

Solutions

1. Use a WebSocketCloseStatus enum constant (e.g. WebSocketCloseStatus.NORMAL_CLOSURE) instead of a raw int
2. Validate the code with WebSocketCloseStatus.isValidStatusCode(code) before constructing the CloseReason
3. Use the code range 3000-4999 for application-specific close codes

Example fix

// before
CloseReason reason = new CloseReason(1006); // reserved, invalid
// after
CloseReason reason = new CloseReason(WebSocketCloseStatus.GOING_AWAY.getCode());

CloseReason safeCloseReason(int code) {
    if (!WebSocketCloseStatus.isValidStatusCode(code))
        throw new IllegalArgumentException("Code not sendable: " + code);
    return new CloseReason(code);
}

When it happens

Trigger: Calling CloseReason(int) or CloseReason(int, String) with a code rejected by WebSocketCloseStatus.isValidStatusCode — e.g. 0, 999, 1004, 1015, or > 4999.

Common situations: Hard-coding a status code read from a spec of another framework; using reserved codes (1004, 1005, 1006, 1015) which must not be sent on the wire; a config property feeding an arbitrary int.

Related errors

• [%s] is not a valid scheme in the base URI %s
• [%s] is not a valid path parameter in the path %s
• Extra steps left over
• Unknown start character for json value: %s
• name cannot be null

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