quarkusio/quarkus · error · IllegalArgumentException

[%s] is not a valid scheme in the base URI %s

Error message

[%s] is not a valid scheme in the base URI %s

What it means

WebSocketConnectorBase.baseUri(URI) validates that the base URI scheme is either ws/wss style secure (isSecure) or http/https style not-secure (isNotSecure). Any other scheme (e.g. ftp:, tcp:, or a malformed URI whose scheme is null) is rejected with this IllegalArgumentException so an invalid WebSocket endpoint URI never reaches the connection attempt.

Source

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

            TlsConfigurationRegistry tlsConfigurationRegistry) {
        this.headers = new HashMap<>();
        this.subprotocols = new HashSet<>();
        this.pathParams = new HashMap<>();
        this.vertx = vertx;
        this.codecs = codecs;
        this.connectionManager = connectionManager;
        this.config = config;
        this.tlsConfigurationRegistry = tlsConfigurationRegistry;
        this.path = "";
        this.pathParamNames = Set.of();
        this.userData = new HashMap<>();
        this.customWebSocketConnectOptions = null;
        this.customWebSocketClientOptions = null;
    }

    public THIS baseUri(URI baseUri) {
        if (!isSecure(baseUri) && !isNotSecure(baseUri)) {
            throw new IllegalArgumentException(
                    String.format("[%s] is not a valid scheme in the base URI %s", baseUri.getScheme(), baseUri));
        }
        this.baseUri = Objects.requireNonNull(baseUri);
        return self();
    }

    public THIS tlsConfigurationName(String tlsConfigurationName) {
        this.tlsConfigurationName = Objects.requireNonNull(tlsConfigurationName);
        return self();
    }

    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);

View on GitHub (pinned to e1c734241f)

Solutions

1. Prefix the URI with a valid scheme: ws://, wss://, http:// or https://
2. Check the config property feeding baseUri() includes an explicit scheme
3. Use URI.create("ws://" + host + path) when the host alone is provided

Example fix

// before
connector.baseUri(URI.create("myhost.example.com/ws"));
// after
connector.baseUri(URI.create("ws://myhost.example.com/ws"));

static void validateBaseUri(URI uri) {
    String s = uri.getScheme();
    if (s == null || !(s.equals("ws") || s.equals("wss") || s.equals("http") || s.equals("https"))) {
        throw new IllegalArgumentException("Invalid scheme: " + s);
    }
}

try {
    connector.baseUri(uri);
} catch (IllegalArgumentException e) {
    log.error("Fix the scheme in baseUri; must be ws/wss/http/https", e);
}

When it happens

Trigger: Calling WebSocketConnector.baseUri(URI) with a URI whose scheme is not ws/wss/http/https — e.g. new URI("myserver.example.com/ws") parsed with no scheme, or a typo like wss:/host.

Common situations: Building the URI from a config property where the user omitted the scheme; concatenating host and path without the ws:// prefix; typos in configuration values.

Related errors

• [%s] is not a valid path parameter in the path %s
• SPIFFE ID exceeds maximum length of 2048 bytes: ${length}
• SPIFFE ID must have 'spiffe://' scheme: ${spiffeId}
• SPIFFE ID is not a valid URI: ${spiffeId}
• SPIFFE ID must not contain userinfo: ${spiffeId}

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