dotnet/aspnetcore · error · Error

The 'HubConnectionBuilder.withUrl' method must be called bef

Error message

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

What it means

Thrown at HubConnectionBuilder.ts:257 by `build()` when `this.url` is falsy, meaning `withUrl()` was never called. The builder requires an HTTP-based URL to construct the underlying HttpConnection; without it, build cannot proceed. The url field is only set by `withUrl` (line 134).

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 294cab2f9b)

Solutions

1. Always call `.withUrl(url)` before `.build()`.
2. If the URL is async, await it before building rather than building with a placeholder.
3. Assert the builder is fully configured in tests: `if (!builder.url) throw ...` before build.
4. Use a factory function that takes url as a required parameter so it can't be forgotten.

Example fix

// before
const hub = new HubConnectionBuilder().configureLogging(LogLevel.Information).build();

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

function buildConnection(builder, url) {
  if (!url) throw new Error('withUrl must be called with a non-empty url before build');
  if (!(builder as any).url) builder.withUrl(url);
  return builder.build();
}

function builderHasUrl(b: HubConnectionBuilder): boolean {
  return !!(b as any).url;
}

try { return builder.build(); }
catch (e) {
  if (/withUrl' method must be called/.test(String(e))) {
    throw new Error('Programming bug: withUrl(url) was never invoked before build()');
  }
  throw e;
}

When it happens

Trigger: Calling `new HubConnectionBuilder().configureLogging(...).build()` without ever invoking `withUrl(url)`. The guard at line 256 fires.

Common situations: Conditional setup that skipped the withUrl branch (e.g. URL came from async config but the builder was built synchronously before the await resolved); refactoring that removed the withUrl line; copy-paste that left only configureLogging/withAutomaticReconnect; typo calling a non-existent `withHubUrl`.

Related errors

• The HubConnection url must be a valid url.
• Unknown log level: ${name}
• A reconnectPolicy has already been set.
• The HubConnection url must be a valid url.
• EqualTo validator requires a non-empty "other" parameter.

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