SignalR/SignalR · error · ArgumentNullException

headers

Error message

headers

What it means

Thrown by WebSocketWrapperRequest.SetRequestHeaders when the headers dictionary is null. The method iterates every header entry to forward it to ClientWebSocket.Options.SetRequestHeader, so a null dictionary cannot be enumerated.

Source

Thrown at src/Microsoft.AspNet.SignalR.Client/Transports/WebSockets/WebSocketWrapperRequest.cs:95

        }

        public string Accept
        {
            get
            {
                return null;
            }
            set
            {

            }
        }

        public void SetRequestHeaders(IDictionary<string, string> headers)
        {
            if (headers == null)
            {
                throw new ArgumentNullException("headers");
            }

            foreach (KeyValuePair<string, string> headerEntry in headers)
            {
                _clientWebSocket.Options.SetRequestHeader(headerEntry.Key, headerEntry.Value);
            }
        }

        public void AddClientCerts(X509CertificateCollection certificates)
        {
            if (certificates == null)
            {
                throw new ArgumentNullException("certificates");
            }

            _clientWebSocket.Options.ClientCertificates = certificates;
        }

View on GitHub (pinned to 693053b89a)

Solutions

1. Pass an empty Dictionary<string,string> instead of null when no custom headers are needed.
2. Initialize the headers collection eagerly so it is never null downstream.
3. Guard with a null check at the call site before delegating to SetRequestHeaders.

Example fix

// before
request.SetRequestHeaders(hasHeaders ? headers : null);

// after
request.SetRequestHeaders(headers ?? new Dictionary<string, string>());

var safeHeaders = headers ?? new Dictionary<string, string>();
request.SetRequestHeaders(safeHeaders);

if (headers is IDictionary<string,string> d && d != null) { request.SetRequestHeaders(d); }

When it happens

Trigger: Calling SetRequestHeaders(null) directly, or passing through a null headers collection from a request builder that produced no headers.

Common situations: Custom IRequest implementations delegating to WebSocketWrapperRequest, or configuration paths where headers are conditionally set and the collection stays null when omitted.

Related errors

• certificates
• connection
• Url cannot contain query string directly. Pass query string
• value
• transport

AI-assisted analysis of SignalR/SignalR@693053b89a (2026-08-13). Data as JSON: /api/errors/b964e3c1ccb5f1c7. Report an issue: GitHub.