quarkusio/quarkus · error · WebSocketException

@OnError callback on @WebSocketClient must not accept WebSoc

Error message

@OnError callback on @WebSocketClient must not accept WebSocketConnection:

What it means

In websockets-next, @WebSocketClient endpoints must use WebSocketClientConnection, and @WebSocket (server) endpoints must use WebSocketConnection. An @OnError callback declared on a client endpoint that accepts a WebSocketConnection parameter fails the build, since that connection type only exists for server endpoints.

Source

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

            b0.return_(encodeMessage(endpointThis, b0, callback, globalErrorHandlers, endpoint, result, metricsSupportEnabled));
        }
    }

    static List<Callback> findErrorHandlers(Target expectedTarget, IndexView index, BeanInfo bean, ClassInfo beanClass,
            CallbackArgumentsBuildItem callbackArguments, TransformedAnnotationsBuildItem transformedAnnotations,
            String endpointPath) {
        List<AnnotationInstance> annotations = findCallbackAnnotations(index, beanClass, WebSocketDotNames.ON_ERROR);
        if (annotations.isEmpty()) {
            return List.of();
        }
        List<Callback> errorHandlers = new ArrayList<>(annotations.size());
        for (AnnotationInstance annotation : annotations) {
            MethodInfo method = annotation.target().asMethod();
            Target target;
            if (method.parameterTypes().stream().map(Type::name).anyMatch(WebSocketDotNames.WEB_SOCKET_CONNECTION::equals)) {
                target = Target.SERVER;
                if (expectedTarget == Target.CLIENT) {
                    throw new WebSocketException("@OnError callback on @WebSocketClient must not accept WebSocketConnection: "
                            + method.declaringClass() + "." + method.name() + "()");
                }
            } else if (method.parameterTypes().stream().map(Type::name)
                    .anyMatch(WebSocketDotNames.WEB_SOCKET_CLIENT_CONNECTION::equals)) {
                target = Target.CLIENT;
                if (expectedTarget == Target.SERVER) {
                    throw new WebSocketException("@OnError callback on @WebSocket must not accept WebSocketClientConnection: "
                            + method.declaringClass() + "." + method.name() + "()");
                }
            } else {
                target = Target.UNDEFINED;
            }
            Callback callback = new Callback(target, annotation, bean, method,
                    executionModel(method, transformedAnnotations), callbackArguments, transformedAnnotations,
                    endpointPath, index);
            long errorArguments = callback.arguments.stream().filter(ca -> ca instanceof ErrorCallbackArgument).count();
            if (errorArguments != 1) {
                throw new WebSocketException(

View on GitHub (pinned to e1c734241f)

Solutions

Replace the WebSocketConnection parameter with WebSocketClientConnection
Fix the import statement to io.quarkus.websockets.next.WebSocketClientConnection
Remove the connection parameter entirely if it is not needed

Example fix

// before (client endpoint)
@OnError
void onError(WebSocketConnection conn, Exception e) {}

// after
import io.quarkus.websockets.next.WebSocketClientConnection;
@OnError
void onError(WebSocketClientConnection conn, Exception e) {}

Defensive patterns

Strategy: validation

Validate before calling

// In a @WebSocketClient class, ensure error handlers use WebSocketClientConnection
@OnError void onError(WebSocketClientConnection conn, Throwable t) {}

Prevention

Client endpoints always use WebSocketClientConnection
Check imports: io.quarkus.websockets.next.WebSocketClientConnection
When copying server handlers to clients, update the connection type

When it happens

Trigger: An @WebSocketClient class contains an @OnError method whose parameter list includes io.quarkus.websockets.next.WebSocketConnection instead of WebSocketClientConnection.

Common situations: Copy-pasting an error handler from a server endpoint into a client endpoint; IDE auto-import picking the wrong Connection class; refactoring a shared handler class.

Related errors

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