microsoft/garnet · error · Exception

Need to provide SslClientAuthenticationOptions when TLS is e

Error message

Need to provide SslClientAuthenticationOptions when TLS is enabled

What it means

Thrown by the client-side NetworkHandler.Start when tlsOptions is non-null but the handler was constructed without TLS (sslStream == null). The client variant: supplying SslClientAuthenticationOptions to a plain-TCP client handler is a configuration contradiction fixed at construction time.

Source

Thrown at libs/common/Networking/NetworkHandler.cs:216

            catch (Exception ex)
            {
                logger?.LogWarning(ex, "An error has occurred");
                readerStatus = TlsReaderStatus.Rest;
                if (expectingData.CurrentCount == 0) expectingData.Release();
                Dispose();
                throw;
            }
        }

        /// <summary>
        /// Begin (background) network handler.
        /// 
        /// Blocks until auth completes.
        /// </summary>
        public virtual void Start(SslClientAuthenticationOptions tlsOptions, string remoteEndpointName = null, CancellationToken token = default)
        {
            if (tlsOptions != null && sslStream == null)
                throw new Exception("Need to provide SslClientAuthenticationOptions when TLS is enabled");
            if (tlsOptions == null && sslStream != null)
                throw new Exception("Cannot provide SslClientAuthenticationOptions when TLS is disabled");
            if (tlsOptions == null && sslStream == null) return;

            // Can't use SslStream's sync methods for auth, so we must block
            AsyncUtils.BlockingWait(AuthenticateAsClientAsync(tlsOptions, remoteEndpointName, token));
        }

        /// <summary>
        /// Begin async network handler (including auth).
        /// 
        /// When tasks completes, authentication has also completed.
        /// </summary>
        public virtual async Task StartAsync(SslClientAuthenticationOptions tlsOptions, string remoteEndpointName = null, CancellationToken token = default)
        {
            if (tlsOptions != null && sslStream == null)
                throw new Exception("Need to provide SslClientAuthenticationOptions when TLS is enabled");
            if (tlsOptions == null && sslStream != null)

View on GitHub (pinned to 951b0fc683)

Solutions

1. Build the client handler with TLS exactly when client auth options will be supplied.
2. Keep the client TLS decision in one place used by both handler construction and Start.
3. Validate sslStream presence matches the options argument at the call site.

// Ensure client handler TLS mode matches options before Start
if (tlsOpts != null && !handler.IsTlsEnabled)
    throw new InvalidOperationException("Cannot start a non-TLS client handler with TLS options");
handler.Start(tlsOpts, remoteEndpointName, token);

When it happens

Trigger: Constructing a client NetworkHandler without an SslStream, then calling Start(SslClientAuthenticationOptions) with non-null options.

Common situations: Client TLS enabled in config but the connection built a non-TLS handler; replication/cluster client wiring where the TLS flag and handler construction disagree.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Cannot provide SslClientAuthenticationOptions when TLS is di
• Need to provide SslServerAuthenticationOptions when TLS is e
• Cannot provide SslServerAuthenticationOptions when TLS is di
• Failed to connect at {endpoint}
• Disconnected

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/79479ca80a6c77b3. Report an issue: GitHub.