dotnet/aspnetcore · error · Error

The HubConnection must be in the Disconnected or…

Error message

The HubConnection must be in the Disconnected or Reconnecting state to change the url.

What it means

Thrown by the `baseUrl` setter on HubConnection when the caller tries to reassign the URL while the connection is in any state other than Disconnected or Reconnecting. The library only permits a URL change when no live transport is established, because changing the URL of an active socket/SSE/poll would invalidate the session.

Solutions

Stop the connection first (`await hubConnection.stop()`), then set the new URL, then `start()` again.
To redirect during recovery, set the URL from the `onreconnecting` callback (Reconnecting state is permitted).
Do not mutate baseUrl from inside invocation handlers while Connected.

Example fix

// before
hubConnection.baseUrl = "https://failover/hub"; // throws if Connected
// after - route through reconnect or stop first
await hubConnection.stop();
hubConnection.baseUrl = "https://failover/hub";
await hubConnection.start();

Defensive patterns

Strategy: validation

Validate before calling

import { HubConnectionState } from "@microsoft/signalr";
function canChangeUrl(hub: { state: HubConnectionState }): boolean {
  return hub.state === HubConnectionState.Disconnected
      || hub.state === HubConnectionState.Reconnecting;
}

Type guard

function isUrlChangeAllowed(state: HubConnectionState): boolean {
  return state === HubConnectionState.Disconnected
      || state === HubConnectionState.Reconnecting;
}

Prevention

Stop the connection before reassigning baseUrl.
Reassign from onreconnecting if you need mid-failure redirection.
Do not mutate baseUrl from inside invocation handlers.

When it happens

Trigger: Calling `hubConnection.baseUrl = newUrl` (or the equivalent set) while `_connectionState` is `Connected` or `Disconnecting` — i.e. after start() has resolved and before stop() has completed.

Common situations: Redirecting a live connection to a failover/DR endpoint after a reconnect event without first stopping, or attempting to repoint the URL from inside an `on('method')` handler while the connection is up.

Related errors

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

Appendix: source

Thrown at src/SignalR/clients/ts/signalr/src/HubConnection.ts:188

     *  in the disconnected state or if the negotiation step was skipped.
     */
    get connectionId(): string | null {
        return this.connection ? (this.connection.connectionId || null) : null;
    }

    /** Indicates the url of the {@link HubConnection} to the server. */
    get baseUrl(): string {
        return this.connection.baseUrl || "";
    }

    /**
     * Sets a new url for the HubConnection. Note that the url can only be changed when the connection is in either the Disconnected or
     * Reconnecting states.
     * @param {string} url The url to connect to.
     */
    set baseUrl(url: string) {
        if (this._connectionState !== HubConnectionState.Disconnected && this._connectionState !== HubConnectionState.Reconnecting) {
            throw new Error("The HubConnection must be in the Disconnected or Reconnecting state to change the url.");
        }

        if (!url) {
            throw new Error("The HubConnection url must be a valid url.");
        }

        this.connection.baseUrl = url;
    }

    /** Starts the connection.
     *
     * @returns {Promise<void>} A Promise that resolves when the connection has been successfully established, or rejects with an error.
     */
    public start(): Promise<void> {
        this._startPromise = this._startWithStateTransitions();
        return this._startPromise;
    }

View on GitHub (pinned to 3600ca084e)