{"record":{"id":"5e882b88996d1830","repo":"microsoft/garnet","slug":"need-to-provide-sslserverauthenticationoptions-whe","errorCode":null,"errorMessage":"Need to provide SslServerAuthenticationOptions when TLS is enabled","messagePattern":"Need to provide SslServerAuthenticationOptions when TLS is enabled","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"libs/common/Networking/NetworkHandler.cs","lineNumber":150,"sourceCode":"                transportReceiveBufferEntry = this.networkPool.Get(this.networkBufferSettings.initialReceiveBufferSize, PoolEntryBufferType.TransportReceiveBuffer);\n                transportReceiveBuffer = transportReceiveBufferEntry.entry;\n                transportReceiveBufferPtr = transportReceiveBufferEntry.entryPtr;\n\n                transportSendBufferEntry = this.networkPool.Get(this.networkBufferSettings.sendBufferSize, PoolEntryBufferType.TransportSendBuffer);\n                transportSendBuffer = transportSendBufferEntry.entry;\n                transportSendBufferPtr = transportSendBufferEntry.entryPtr;\n            }\n        }\n\n        /// <summary>\n        /// Begin (background) network handler.\n        /// \n        /// Blocks until auth completes.\n        /// </summary>\n        public virtual void Start(SslServerAuthenticationOptions tlsOptions = null, string remoteEndpointName = null, CancellationToken token = default)\n        {\n            if (tlsOptions != null && sslStream == null)\n                throw new Exception(\"Need to provide SslServerAuthenticationOptions when TLS is enabled\");\n            if (tlsOptions == null && sslStream != null)\n                throw new Exception(\"Cannot provide SslServerAuthenticationOptions when TLS is disabled\");\n            if (tlsOptions == null && sslStream == null) return;\n\n            // Can't use SslStream's sync methods for auth, so we must block\n            AsyncUtils.BlockingWait(AuthenticateAsServerAsync(tlsOptions, remoteEndpointName, token));\n        }\n\n        /// <summary>\n        /// Begin async network handler.\n        /// </summary>\n        public virtual async Task StartAsync(SslServerAuthenticationOptions tlsOptions = null, string remoteEndpointName = null, CancellationToken token = default)\n        {\n            if (tlsOptions != null && sslStream == null)\n                throw new Exception(\"Need to provide SslServerAuthenticationOptions when TLS is enabled\");\n            if (tlsOptions == null && sslStream != null)\n                throw new Exception(\"Cannot provide SslServerAuthenticationOptions when TLS is disabled\");\n            if (tlsOptions == null && sslStream == null) return;","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/microsoft/garnet/blob/951b0fc6838721f89d102c2bbe1b914e8d39d700/libs/common/Networking/NetworkHandler.cs#L132-L168","documentation":"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.","triggerScenarios":"Constructing a NetworkHandler/SslStream-less and then calling Start(SslServerAuthenticationOptions) with non-null options.","commonSituations":"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.","solutions":["Keep TLS config consistent: only pass SslServerAuthenticationOptions when the handler was built with an SslStream.","Verify the listener-creation code path supplies an SslStream exactly when TLS is enabled.","Centralize the TLS decision in one config read used by both handler construction and Start."],"exampleFix":"// before\nhandler.Start(tlsEnabled ? tlsOpts : null);\n// after\nvar handler = tlsEnabled ? new NetworkHandler(..., useTls: true) : new NetworkHandler(..., useTls: false);\nhandler.Start(tlsEnabled ? tlsOpts : null);","handlingStrategy":"validation","validationCode":"// Ensure handler TLS mode matches the options presence before Start\nif (tlsOpts != null && !handler.IsTlsEnabled)\n    throw new InvalidOperationException(\"Cannot start a non-TLS handler with TLS options\");\nhandler.Start(tlsOpts, remoteEndpointName, token);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Single-source the TLS decision so handler construction and Start agree.","Only construct an SslStream-bearing handler when TLS is enabled.","Assert the sslStream/options pairing at the call site."],"tags":["network","tls","server","config","garnet"],"backgroundTag":null,"analyzedSha":"951b0fc6838721f89d102c2bbe1b914e8d39d700","analyzedAt":"2026-08-13T19:01:32.939Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}