quarkusio/quarkus · error · IllegalStateException

Only one server SendingInterceptor is supported

Error message

Only one server SendingInterceptor is supported

What it means

Thrown by WebSocketTelemetryProviderBuilder.pathToServerSendingInterceptor when a second server SendingInterceptor registration arrives while one is already installed (the field is non-null). The builder currently supports exactly one interceptor of this kind — the comment notes a composite could be added later — so the duplicate registration guard rejects it, mirroring the sibling pathToClientErrorInterceptor check for ErrorInterceptor.

Source

Thrown at extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/telemetry/WebSocketTelemetryProviderBuilder.java:127

    }

    void pathToClientErrorInterceptor(Function<String, ErrorInterceptor> pathToClientErrorInterceptor) {
        Objects.requireNonNull(pathToClientErrorInterceptor);
        if (this.pathToClientErrorInterceptor == null) {
            this.pathToClientErrorInterceptor = pathToClientErrorInterceptor;
        } else {
            // we can implement composite if we need this in the future
            throw new IllegalStateException("Only one client ErrorInterceptor is supported");
        }
    }

    void pathToServerSendingInterceptor(Function<String, SendingInterceptor> pathToServerSendingInterceptor) {
        Objects.requireNonNull(pathToServerSendingInterceptor);
        if (this.pathToServerSendingInterceptor == null) {
            this.pathToServerSendingInterceptor = pathToServerSendingInterceptor;
        } else {
            // we can implement composite if we need this in the future
            throw new IllegalStateException("Only one server SendingInterceptor is supported");
        }
    }

    void pathToClientSendingInterceptor(Function<String, SendingInterceptor> pathToClientSendingInterceptor) {
        Objects.requireNonNull(pathToClientSendingInterceptor);
        if (this.pathToClientSendingInterceptor == null) {
            this.pathToClientSendingInterceptor = pathToClientSendingInterceptor;
        } else {
            // we can implement composite if we need this in the future
            throw new IllegalStateException("Only one client SendingInterceptor is supported");
        }
    }

    WebSocketTelemetryProvider build() {
        return new WebSocketTelemetryProvider(serverEndpointDecorator, clientEndpointDecorator,
                pathToClientConnectionInterceptor, pathToServerConnectionInterceptor, pathToClientSendingInterceptor,
                pathToServerSendingInterceptor, pathToClientErrorInterceptor, pathToServerErrorInterceptor);
    }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Register only one server sending interceptor function
  2. Combine interceptor logic into a single composite Function
  3. Identify and remove the duplicate contributor

Example fix

// before
builder.pathToServerSendingInterceptor(a);
builder.pathToServerSendingInterceptor(b);
// after
builder.pathToServerSendingInterceptor(path -> path.startsWith("/ws") ? b.apply(path) : a.apply(path));
Defensive patterns

Strategy: validation

Validate before calling

if (builder.pathToServerSendingInterceptor != null) throw new IllegalStateException("already registered");

Try / catch

try { builder.pathToServerSendingInterceptor(fn); } catch (IllegalStateException e) { /* handle duplicate */ }

Prevention

When it happens

Trigger: Calling pathToServerSendingInterceptor(...) when the field is already non-null.

Common situations: Multiple telemetry providers or extensions each contributing a server sending interceptor during the same build/initialization.

Related errors

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