dotnet/aspnetcore · error · Error

withCredentials option was not a 'boolean' or 'undefined' va

Error message

withCredentials option was not a 'boolean' or 'undefined' value

What it means

Thrown by the HttpConnection constructor when the IHttpConnectionOptions.withCredentials field is present but is neither a boolean nor undefined. The constructor uses this value to decide whether cross-site XHR/fetch requests carry cookies and credentials, so an invalid type would propagate as ambiguous behavior. The guard at HttpConnection.ts:92-96 fails fast instead of coercing.

Source

Thrown at src/SignalR/clients/ts/signalr/src/HttpConnection.ts:95

    public baseUrl: string;
    public connectionId?: string;
    public onreceive: ((data: string | ArrayBuffer) => void) | null;
    public onclose: ((e?: Error) => void) | null;

    private readonly _negotiateVersion: number = 1;

    constructor(url: string, options: IHttpConnectionOptions = {}) {
        Arg.isRequired(url, "url");

        this._logger = createLogger(options.logger);
        this.baseUrl = this._resolveUrl(url);

        options = options || {};
        options.logMessageContent = options.logMessageContent === undefined ? false : options.logMessageContent;
        if (typeof options.withCredentials === "boolean" || options.withCredentials === undefined) {
            options.withCredentials = options.withCredentials === undefined ? true : options.withCredentials;
        } else {
            throw new Error("withCredentials option was not a 'boolean' or 'undefined' value");
        }
        options.timeout = options.timeout === undefined ? 100 * 1000 : options.timeout;

        let webSocketModule: any = null;
        let eventSourceModule: any = null;

        if (Platform.isNode && typeof require !== "undefined") {
            // In order to ignore the dynamic require in webpack builds we need to do this magic
            // @ts-ignore: TS doesn't know about these names
            const requireFunc = typeof __webpack_require__ === "function" ? __non_webpack_require__ : require;
            webSocketModule = requireFunc("ws");
            eventSourceModule = requireFunc("eventsource");
        }

        if (!Platform.isNode && typeof WebSocket !== "undefined" && !options.WebSocket) {
            options.WebSocket = WebSocket;
        } else if (Platform.isNode && !options.WebSocket) {
            if (webSocketModule) {

View on GitHub (pinned to 294cab2f9b)

Solutions

1. Coerce the value to a boolean before passing it: `options.withCredentials = Boolean(options.withCredentials)` or `options.withCredentials = options.withCredentials === true`.
2. If loading config from JSON/env, parse explicitly: `withCredentials: String(config.CORS_CREDENTIALS).toLowerCase() === 'true'`.
3. Omit the field entirely to accept the default of `true`.
4. Delete the field if previously set to a non-boolean: `delete options.withCredentials`.

Example fix

// before
const options = { withCredentials: "true" };
new HttpConnection(url, options);

// after
const options = { withCredentials: String(config.withCredentials).toLowerCase() === 'true' };
new HttpConnection(url, options);

function sanitizeHttpOptions(opts) {
  if (opts && 'withCredentials' in opts) {
    const v = opts.withCredentials;
    if (typeof v !== 'boolean' && v !== undefined) {
      // coerce or throw early with a clear message
      opts.withCredentials = v === 'true' || v === 1 || v === 'yes';
    }
  }
  return opts;
}
// use: new HttpConnection(url, sanitizeHttpOptions(rawOptions));

function isWithCredentials(v: unknown): v is boolean | undefined {
  return v === undefined || typeof v === 'boolean';
}

try {
  const conn = new HttpConnection(url, options);
} catch (e) {
  if (/withCredentials/.test(String(e))) {
    options.withCredentials = Boolean(options.withCredentials);
    return new HttpConnection(url, options);
  }
  throw e;
}

When it happens

Trigger: Constructing `new HttpConnection(url, options)` or `HubConnectionBuilder.withUrl(url, options)` where `options.withCredentials` is a string (e.g. "true"), a number (e.g. 1), an object, or null. The check rejects anything where `typeof` is not exactly "boolean" or "undefined".

Common situations: Reading the value from a JSON config file or environment variable where it arrives as the string "true"/"false"; deserializing options from query strings; passing a truthy non-boolean like 1 or "yes"; assigning `null` to explicitly disable it (null is typeof "object").

Related errors

• Authentication refreshBeforeExpirationInMilliseconds must be
• A valid url is required.
• 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/79186f7106f001ff. Report an issue: GitHub.