{"record":{"id":"fce7e479f1f8f316","repo":"microsoft/garnet","slug":"certsubjectname-is-supported-only-on-windows","errorCode":null,"errorMessage":"CertSubjectName is supported only on Windows.","messagePattern":"CertSubjectName is supported only on Windows\\.","errorType":"exception","errorClass":"GarnetException","httpStatus":null,"severity":"error","filePath":"libs/server/TLS/GarnetTlsOptions.cs","lineNumber":140,"sourceCode":"        SslServerAuthenticationOptions GetSslServerAuthenticationOptions()\n        {\n            if (CertFileName == null && CertSubjectName == null)\n            {\n                logger?.LogError(\"CertFileName and CertSubjectName cannot both be null.\");\n                throw new GarnetException(\"CertFileName and CertSubjectName cannot both be null.\");\n            }\n\n            if (CertFileName != null && CertSubjectName != null)\n            {\n                logger?.LogError(\"Cannot use CertFileName with CertSubjectName. Provide only one of them.\");\n                throw new GarnetException(\"Cannot use CertFileName with CertSubjectName. Provide only one of them.\");\n            }\n\n            // We support CertSubjectName only on Windows\n            if (CertSubjectName != null && !RuntimeInformation.IsOSPlatform(OSPlatform.Windows))\n            {\n                logger?.LogError(\"CertSubjectName is supported only on Windows.\");\n                throw new GarnetException(\"CertSubjectName is supported only on Windows.\");\n            }\n\n            if (CertificateRefreshFrequency < 0)\n            {\n                logger?.LogError(\"CertificateRefreshFrequency should not be less than 0.\");\n                throw new GarnetException(\"CertificateRefreshFrequency should not be less than 0.\");\n            }\n\n            // End timer associated with old certificate selector, if any\n            serverCertificateSelector?.EndTimer();\n\n            // Create new certificate selector\n            if (CertSubjectName == null)\n                serverCertificateSelector = new ServerCertificateSelector(CertFileName, CertPassword, CertificateRefreshFrequency, logger);\n            else\n                serverCertificateSelector = new ServerCertificateSelector(CertSubjectName, CertificateRefreshFrequency, logger);\n\n            return new SslServerAuthenticationOptions","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/microsoft/garnet/blob/951b0fc6838721f89d102c2bbe1b914e8d39d700/libs/server/TLS/GarnetTlsOptions.cs#L122-L158","documentation":"Garnet's certificate store lookup (FindBySubjectName on X509Store) is a Windows-only API. On Linux or macOS, specifying CertSubjectName causes GetSslServerAuthenticationOptions() to throw immediately, before any store access is attempted. This is a platform guard, not a runtime certificate-not-found error.","triggerScenarios":"Running Garnet on Linux or macOS with --cert-subject-name set. The check is CertSubjectName != null && !RuntimeInformation.IsOSPlatform(OSPlatform.Windows).","commonSituations":"Deploying a Windows-developed config to a Linux container without changing cert source; using the same config file across Windows dev and Linux production; Docker image based on Linux with a Windows-style cert config.","solutions":["Switch to --cert-file-name <path> --cert-password <password> on Linux/macOS.","If running in Docker, mount the certificate file and update the config.","Use platform-conditional configuration (e.g., separate config files for Windows vs Linux deployments)."],"exampleFix":"// before (on Linux)\n--cert-subject-name CN=garnet.local\n\n// after (on Linux)\n--cert-file-name /etc/garnet/cert.pfx --cert-password mypassword","handlingStrategy":"validation","validationCode":"if (!string.IsNullOrEmpty(options.CertSubjectName) && !OperatingSystem.IsWindows())\n    throw new PlatformNotSupportedException(\"--cert-subject-name is Windows-only. Use --cert-file-name on this platform.\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["On Linux/macOS, always use --cert-file-name instead of --cert-subject-name.","Maintain separate config files per platform for cert source.","In Docker builds, mount the cert file and set --cert-file-name in the entrypoint."],"tags":["tls","certificate","configuration","platform","linux","garnet"],"backgroundTag":null,"analyzedSha":"951b0fc6838721f89d102c2bbe1b914e8d39d700","analyzedAt":"2026-08-13T19:01:32.939Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}