dotnet/aspnetcore · error · Error

The HubConnection url must be a valid url.

Error message

The HubConnection url must be a valid url.

What it means

Thrown by the `baseUrl` setter on HubConnection when the new value is falsy (`undefined`, `null`, or empty string). The setter runs after the state guard, so it only fires when the state check has passed; reaching this throw means the state is valid but the URL is empty.

Solutions

1. Validate the URL string is non-empty before assigning it to baseUrl.
2. Source the URL from a typed config object with a default value.
3. Fail fast at app startup if the required URL env var is missing.

Example fix

// before
hubConnection.baseUrl = process.env.HUB_URL;
// after
const url = process.env.HUB_URL;
if (!url) throw new Error("HUB_URL not configured");
hubConnection.baseUrl = url;

function requireUrl(url: string | undefined): string {
  if (!url) throw new Error("Hub URL is required");
  return url;
}

function isNonEmptyString(v: unknown): v is string {
  return typeof v === "string" && v.length > 0;
}

When it happens

Trigger: Assigning an empty/undefined value to `hubConnection.baseUrl`, typically because a config lookup returned undefined (e.g. `process.env.HUB_URL` not set) or a variable was reset to empty.

Common situations: Missing environment variable in production, race where the config loader has not populated the URL yet, or accidentally passing the result of an expression that evaluates to ''.

Related errors

• A valid url is required.
• Authentication refreshBeforeExpirationInMilliseconds must…
• Cannot resolve ' '.
• The 'HubConnectionBuilder.withUrl' method must be called…
• Unknown log level

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

Appendix: source

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

    }

    /** 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;
    }

    private async _startWithStateTransitions(): Promise<void> {
        if (this._connectionState !== HubConnectionState.Disconnected) {
            return Promise.reject(new Error("Cannot start a HubConnection that is not in the 'Disconnected' state."));
        }

View on GitHub (pinned to 3600ca084e)