microsoft/garnet · error · Exception

Need to provide SslServerAuthenticationOptions when TLS is e

Error message

Need to provide SslServerAuthenticationOptions when TLS is enabled

What it means

Thrown by the server-side NetworkHandler.Start when tlsOptions is non-null but the handler was constructed without TLS (sslStream == null). The handler's TLS capability is fixed at construction; passing server auth options to a plain-TCP handler is a configuration contradiction.

Source

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

                transportReceiveBufferEntry = this.networkPool.Get(this.networkBufferSettings.initialReceiveBufferSize, PoolEntryBufferType.TransportReceiveBuffer);
                transportReceiveBuffer = transportReceiveBufferEntry.entry;
                transportReceiveBufferPtr = transportReceiveBufferEntry.entryPtr;

                transportSendBufferEntry = this.networkPool.Get(this.networkBufferSettings.sendBufferSize, PoolEntryBufferType.TransportSendBuffer);
                transportSendBuffer = transportSendBufferEntry.entry;
                transportSendBufferPtr = transportSendBufferEntry.entryPtr;
            }
        }

        /// <summary>
        /// Begin (background) network handler.
        /// 
        /// Blocks until auth completes.
        /// </summary>
        public virtual void Start(SslServerAuthenticationOptions tlsOptions = null, string remoteEndpointName = null, CancellationToken token = default)
        {
            if (tlsOptions != null && sslStream == null)
                throw new Exception("Need to provide SslServerAuthenticationOptions when TLS is enabled");
            if (tlsOptions == null && sslStream != null)
                throw new Exception("Cannot provide SslServerAuthenticationOptions 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(AuthenticateAsServerAsync(tlsOptions, remoteEndpointName, token));
        }

        /// <summary>
        /// Begin async network handler.
        /// </summary>
        public virtual async Task StartAsync(SslServerAuthenticationOptions tlsOptions = null, string remoteEndpointName = null, CancellationToken token = default)
        {
            if (tlsOptions != null && sslStream == null)
                throw new Exception("Need to provide SslServerAuthenticationOptions when TLS is enabled");
            if (tlsOptions == null && sslStream != null)
                throw new Exception("Cannot provide SslServerAuthenticationOptions when TLS is disabled");
            if (tlsOptions == null && sslStream == null) return;

View on GitHub (pinned to 951b0fc683)

Solutions

1. Keep TLS config consistent: only pass SslServerAuthenticationOptions when the handler was built with an SslStream.
2. Verify the listener-creation code path supplies an SslStream exactly when TLS is enabled.
3. Centralize the TLS decision in one config read used by both handler construction and Start.

Example fix

// before
handler.Start(tlsEnabled ? tlsOpts : null);
// after
var handler = tlsEnabled ? new NetworkHandler(..., useTls: true) : new NetworkHandler(..., useTls: false);
handler.Start(tlsEnabled ? tlsOpts : null);

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

When it happens

Trigger: Constructing a NetworkHandler/SslStream-less and then calling Start(SslServerAuthenticationOptions) with non-null options.

Common situations: TLS enabled in app config but the listener created a non-TLS handler (or vice-versa); a wiring bug where the TLS flag and the sslStream presence disagree at startup.

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 SslServerAuthenticationOptions when TLS is di
• Need to provide SslClientAuthenticationOptions when TLS is e
• Cannot provide SslClientAuthenticationOptions when TLS is di
• Failed to connect at {endpoint}
• VectorSetReplayTaskCount should be in range [0,{Environment.

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