microsoft/garnet · error · Exception

Cannot provide SslServerAuthenticationOptions when TLS is di

Error message

Cannot provide SslServerAuthenticationOptions when TLS is disabled

What it means

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

Source

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

                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;

            await AuthenticateAsServerAsync(tlsOptions, remoteEndpointName, token).ConfigureAwait(false);

View on GitHub (pinned to 951b0fc683)

Solutions

1. Always supply SslServerAuthenticationOptions when the handler is TLS-enabled.
2. Validate that a TLS-enabled handler has a non-null options object before calling Start.
3. Fail fast at config load if TLS is enabled but no cert/options are configured.

Example fix

// before
handler.Start();
// after
handler.Start(tlsOpts ?? throw new InvalidOperationException("TLS handler requires server auth options"));

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

When it happens

Trigger: Constructing a NetworkHandler with an SslStream, then calling Start() with null tlsOptions.

Common situations: TLS handler created (TLS on) but the caller forgets to pass SslServerAuthenticationOptions; a config read that returns null options while the handler is TLS-capable.

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 SslServerAuthenticationOptions when TLS is e
• 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/2eb720e60eeed771. Report an issue: GitHub.