dotnet/aspnetcore · error · IllegalArgumentException

A valid url is required.

Error message

A valid url is required.

What it means

An IllegalArgumentException thrown by the HubConnection constructor when the url argument is null or empty. The connection requires a non-null, non-empty endpoint to negotiate and establish a transport, so construction fails immediately rather than deferring the failure to start(). This is the earliest validation point in the HubConnectionBuilder pipeline.

Source

Thrown at src/SignalR/clients/java/signalr/core/src/main/java/com/microsoft/signalr/HubConnection.java:128

        }
        return null;
    }

    // For testing purposes
    void setTickRate(long tickRateInMilliseconds) {
        this.tickRate = tickRateInMilliseconds;
    }

    // For testing purposes
    Transport getTransport() {
        return this.state.getConnectionState().transport;
    }

    HubConnection(String url, Transport transport, boolean skipNegotiate, HttpClient httpClient, HubProtocol protocol,
                  Single<String> accessTokenProvider, long handshakeResponseTimeout, Map<String, String> headers, TransportEnum transportEnum,
                  Action1<OkHttpClient.Builder> configureBuilder, long serverTimeout, long keepAliveInterval) {
        if (url == null || url.isEmpty()) {
            throw new IllegalArgumentException("A valid url is required.");
        }

        this.state = new ReconnectingConnectionState(this.logger);
        this.baseUrl = url;
        this.protocol = protocol;

        if (accessTokenProvider != null) {
            this.accessTokenProvider = accessTokenProvider;
        } else {
            this.accessTokenProvider = Single.just("");
        }

        if (httpClient != null) {
            this.httpClient = httpClient;
        } else {
            this.httpClient = new DefaultHttpClient(configureBuilder);
        }

View on GitHub (pinned to 294cab2f9b)

Solutions

1. Provide a non-empty, valid URL string to HubConnectionBuilder.create(url).
2. Validate the URL is non-null and non-empty before building the HubConnection, failing config loading early with a clear message.
3. Check that the configuration source (env var, properties file) actually defines the endpoint value.

Example fix

// before
String endpoint = config.get("signalr.url"); // null if missing
HubConnection connection = HubConnectionBuilder.create(endpoint).build();

// after
String endpoint = config.get("signalr.url");
if (endpoint == null || endpoint.isEmpty()) {
    throw new IllegalStateException("signalr.url must be configured");
}
HubConnection connection = HubConnectionBuilder.create(endpoint).build();

String url = config.get("signalr.url");
if (url == null || url.isEmpty()) {
    throw new IllegalStateException("Missing signalr.url configuration");
}
// Optionally validate URL format
try { new java.net.URL(url); } catch (Exception e) { throw new IllegalArgumentException("Invalid signalr.url: " + url); }
HubConnection conn = HubConnectionBuilder.create(url).build();

try {
    HubConnection conn = HubConnectionBuilder.create(url).build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("valid url")) {
        // handle missing configuration
    }
    throw e;
}

When it happens

Trigger: Calling HubConnectionBuilder.create(null), HubConnectionBuilder.create(""), or building a URL string that resolves to null/empty (e.g. a misconfigured property or environment variable that yields null) and passing it to the builder.

Common situations: Configuration property for the SignalR endpoint is missing or unset in application.properties/yaml, so the injected value is null. A dynamically constructed URL where a required component (host, path) is null causing the whole concatenation to be null or empty. Using the builder before the URL is known (e.g. during early init).

Related errors

• The HubConnection url must be a valid url.
• A valid url is required.
• withCredentials option was not a 'boolean' or 'undefined' va
• Authentication refreshBeforeExpirationInMilliseconds must be
• '%s' already has a value returning handler. Multiple return

AI-assisted analysis of dotnet/aspnetcore@294cab2f9b (2026-08-06). Data as JSON: /api/errors/6317061cb5c699a0. Report an issue: GitHub.