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 in the baseUrl setter (HubConnection.ts:192) when the new url value is falsy (empty string, null, undefined, 0). A HubConnection requires a real target endpoint, so an empty URL is rejected. The check at line 191 uses `if (!url)`.

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

Solutions

1. Validate the URL is non-empty before assigning: `if (newUrl) hub.baseUrl = newUrl;`.
2. Provide a default: `hub.baseUrl = newUrl || fallbackUrl`.
3. Check the source of the URL (env var, config) for typos or unset values.
4. Use `new URL(newUrl)` to validate it parses as a real URL before assigning.

Example fix

// before
hub.baseUrl = process.env.HUB_URL; // undefined -> throws

// after
const url = process.env.HUB_URL;
if (url) hub.baseUrl = url;
else throw new Error('HUB_URL not configured');

function setHubUrl(hub, url) {
  if (!url || typeof url !== 'string' || !url.trim()) {
    throw new Error('A non-empty url string is required');
  }
  hub.baseUrl = url;
}

function isNonEmptyUrlString(u: unknown): u is string {
  return typeof u === 'string' && u.trim().length > 0;
}

try { hub.baseUrl = candidate; }
catch (e) {
  if (/must be a valid url/.test(String(e))) {
    throw new Error('config did not provide a hub url');
  }
  throw e;
}

When it happens

Trigger: Setting `hub.baseUrl = ''`, `hub.baseUrl = null`, `hub.baseUrl = undefined`, or passing an empty string variable that came from a failed config load. Runs after the state check passes (Disconnected/Reconnecting).

Common situations: Loading URL from config/env that wasn't set (`process.env.HUB_URL` returns undefined); a UI field that allowed empty submission; a redirect/variable shadowing bug producing an empty string; clearing the URL by accident before reassignment.

Related errors

• The 'HubConnectionBuilder.withUrl' method must be called bef
• The HubConnection url must be a valid url.
• EqualTo validator requires a non-empty "other" parameter.
• FileExtensions validator requires a non-empty "extensions" p
• Range validator requires at least one of "min" or "max" para

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