What causes "Endpoint URI not set!" in quarkusio/quarkus?

Call .baseUri(String) on the connector before connect()

quarkusio/quarkus · error · WebSocketClientException

Endpoint URI not set!

Error message

Endpoint URI not set!

What it means

BasicWebSocketConnectorImpl.connect() requires an endpoint URI configured beforehand via the connector's baseUri builder methods. Calling connect() without ever setting the URI throws WebSocketClientException 'Endpoint URI not set!'.

Source

Thrown at extensions/websockets-next/runtime/src/main/java/io/quarkus/websockets/next/runtime/BasicWebSocketConnectorImpl.java:126

        return self();
    }

    @Override
    public BasicWebSocketConnector onClose(BiConsumer<WebSocketClientConnection, CloseReason> consumer) {
        this.closeHandler = Objects.requireNonNull(consumer);
        return self();
    }

    @Override
    public BasicWebSocketConnector onError(BiConsumer<WebSocketClientConnection, Throwable> consumer) {
        this.errorHandler = Objects.requireNonNull(consumer);
        return self();
    }

    @Override
    public Uni<WebSocketClientConnection> connect() {
        if (baseUri == null) {
            throw new WebSocketClientException("Endpoint URI not set!");
        }

        // A new client is created for each connection
        // The client is created when the returned Uni is subscribed
        // The client is closed when the connection is closed
        AtomicReference<WebSocketClient> client = new AtomicReference<>();

        WebSocketConnectOptions connectOptions = newConnectOptions(baseUri);
        StringBuilder requestUri = new StringBuilder();
        String mergedPath = mergePath(baseUri.getPath(), replacePathParameters(path));
        requestUri.append(mergedPath);
        if (baseUri.getQuery() != null) {
            requestUri.append("?").append(baseUri.getQuery());
        }
        connectOptions.setURI(requestUri.toString());
        for (Entry<String, List<String>> e : headers.entrySet()) {
            for (String val : e.getValue()) {
                connectOptions.addHeader(e.getKey(), val);

View on GitHub (pinned to e1c734241f)

Solutions

Call .baseUri(String) on the connector before connect()
Make the URI come from application config and assert it is non-null before creating the connector
Prefer WebSocketClient client injection with @WebSocketClient endpoint, which resolves the URI automatically

Example fix

// before
BasicWebSocketConnector.create().connect().await().indefinitely();
// after
BasicWebSocketConnector.create()
    .baseUri("ws://localhost:8080/ws")
    .connect().await().indefinitely();

Defensive patterns

Strategy: validation

Validate before calling

var connector = BasicWebSocketConnector.create();
Objects.requireNonNull(endpointUri, "Endpoint URI must be set before connect()");
connector.baseUri(endpointUri).connect();

Prevention

Always call baseUri(...) immediately after BasicWebSocketConnector.create()
Back the URI with config and fail fast at startup if it is missing
Prefer @WebSocketClient injection which wires the URI automatically

When it happens

Trigger: Instantiating BasicWebSocketConnector (e.g. via BasicWebSocketConnector.create()) and calling connect() without calling .baseUri(...) first, or after a builder path that reset the URI.

Common situations: Building the connector programmatically and forgetting the baseUri step; deriving the URI from config that resolved to null; refactoring the fluent chain and dropping the baseUri call.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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