dotnet/aspnetcore · error · Error

The 'HubConnectionBuilder.withUrl' method must be called…

Error message

The 'HubConnectionBuilder.withUrl' method must be called before building the connection.

What it means

Thrown by HubConnectionBuilder.build when `this.url` is unset. The builder requires a URL to construct the HttpConnection; withUrl is the only method that populates `this.url`, so build() refuses to construct an HttpConnection with no endpoint.

Solutions

1. Always call `.withUrl(url)` before `.build()`.
2. Make withUrl the first call in the builder chain for visibility.
3. Assert `builder.url` is set in test fixtures before build.

Example fix

// before
const conn = new HubConnectionBuilder().configureLogging(LogLevel.Information).build();
// after
const conn = new HubConnectionBuilder()
  .withUrl("/hub")
  .configureLogging(LogLevel.Information)
  .build();

function ensureUrlSet(b: { url?: string }) {
  if (!b.url) throw new Error("withUrl must be called before build");
}

function builderHasUrl(b: { url?: string }): b is { url: string } {
  return typeof b.url === "string" && b.url.length > 0;
}

When it happens

Trigger: Calling `.build()` on a HubConnectionBuilder without a preceding `.withUrl(url)` call, or withUrl was invoked on a different builder instance.

Common situations: Refactoring that moves withUrl behind a conditional that evaluates false, or copy-pasting a builder setup and dropping the withUrl line.

Related errors

• A reconnectPolicy has already been set.
• A valid url is required.
• Cannot resolve ' '.
• The HubConnection url must be a valid url.
• ' ' is flagged with SingleDelivery, but the selected…

AI-assisted analysis of dotnet/aspnetcore@3600ca084e (2026-08-11). Data as JSON: /api/errors/ac8112f0f43fb565. Report an issue: GitHub.

Appendix: source

Thrown at src/SignalR/clients/ts/signalr/src/HubConnectionBuilder.ts:257

    /** Creates a {@link @microsoft/signalr.HubConnection} from the configuration options specified in this builder.
     *
     * @returns {HubConnection} The configured {@link @microsoft/signalr.HubConnection}.
     */
    public build(): HubConnection {
        // If httpConnectionOptions has a logger, use it. Otherwise, override it with the one
        // provided to configureLogger
        const httpConnectionOptions = this.httpConnectionOptions || {};

        // If it's 'null', the user **explicitly** asked for null, don't mess with it.
        if (httpConnectionOptions.logger === undefined) {
            // If our logger is undefined or null, that's OK, the HttpConnection constructor will handle it.
            httpConnectionOptions.logger = this.logger;
        }

        // Now create the connection
        if (!this.url) {
            throw new Error("The 'HubConnectionBuilder.withUrl' method must be called before building the connection.");
        }
        const connection = new HttpConnection(this.url, httpConnectionOptions);

        return HubConnection.create(
            connection,
            this.logger || NullLogger.instance,
            this.protocol || new JsonHubProtocol(),
            this.reconnectPolicy,
            this._serverTimeoutInMilliseconds,
            this._keepAliveIntervalInMilliseconds,
            this._statefulReconnectBufferSize,
            this._authenticationRefreshOptions);
    }
}

function isLogger(logger: any): logger is ILogger {
    return logger.log !== undefined;
}

View on GitHub (pinned to 3600ca084e)