microsoft/garnet · error · Exception

Cannot provide SslClientAuthenticationOptions when TLS is di

Error message

Cannot provide SslClientAuthenticationOptions when TLS is disabled

What it means

Thrown by the client-side NetworkHandler.Start when tlsOptions is null but the handler is TLS-enabled (sslStream != null). A TLS client handler cannot authenticate without SslClientAuthenticationOptions, so omitting them is a configuration contradiction.

Source

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

                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)
                throw new Exception("Cannot provide SslClientAuthenticationOptions when TLS is disabled");
            if (tlsOptions == null && sslStream == null) return;

View on GitHub (pinned to 951b0fc683)

Solutions

1. Always supply non-null SslClientAuthenticationOptions when the client handler is TLS-enabled.
2. Validate options presence before calling Start.
3. Fail fast at config load if client TLS is enabled but options are missing.

// Ensure a TLS-enabled client handler gets non-null options
if (handler.IsTlsEnabled && tlsOpts == null)
    throw new InvalidOperationException("TLS-enabled client handler requires SslClientAuthenticationOptions");
handler.Start(tlsOpts, remoteEndpointName, token);

When it happens

Trigger: Constructing a client handler with an SslStream, then calling Start() with null client auth options.

Common situations: TLS client handler created but the caller forgets to pass SslClientAuthenticationOptions; a config read returning null options for a TLS-capable client.

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

• Need to provide SslClientAuthenticationOptions when TLS is e
• 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/bf0a358e7eff7e19. Report an issue: GitHub.