microsoft/garnet · error · GarnetException

CertSubjectName is supported only on Windows.

Error message

CertSubjectName is supported only on Windows.

What it means

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.

Source

Thrown at libs/server/TLS/GarnetTlsOptions.cs:140

        SslServerAuthenticationOptions GetSslServerAuthenticationOptions()
        {
            if (CertFileName == null && CertSubjectName == null)
            {
                logger?.LogError("CertFileName and CertSubjectName cannot both be null.");
                throw new GarnetException("CertFileName and CertSubjectName cannot both be null.");
            }

            if (CertFileName != null && CertSubjectName != null)
            {
                logger?.LogError("Cannot use CertFileName with CertSubjectName. Provide only one of them.");
                throw new GarnetException("Cannot use CertFileName with CertSubjectName. Provide only one of them.");
            }

            // We support CertSubjectName only on Windows
            if (CertSubjectName != null && !RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
            {
                logger?.LogError("CertSubjectName is supported only on Windows.");
                throw new GarnetException("CertSubjectName is supported only on Windows.");
            }

            if (CertificateRefreshFrequency < 0)
            {
                logger?.LogError("CertificateRefreshFrequency should not be less than 0.");
                throw new GarnetException("CertificateRefreshFrequency should not be less than 0.");
            }

            // End timer associated with old certificate selector, if any
            serverCertificateSelector?.EndTimer();

            // Create new certificate selector
            if (CertSubjectName == null)
                serverCertificateSelector = new ServerCertificateSelector(CertFileName, CertPassword, CertificateRefreshFrequency, logger);
            else
                serverCertificateSelector = new ServerCertificateSelector(CertSubjectName, CertificateRefreshFrequency, logger);

            return new SslServerAuthenticationOptions

View on GitHub (pinned to 951b0fc683)

Solutions

1. Switch to --cert-file-name <path> --cert-password <password> on Linux/macOS.
2. If running in Docker, mount the certificate file and update the config.
3. Use platform-conditional configuration (e.g., separate config files for Windows vs Linux deployments).

Example fix

// before (on Linux)
--cert-subject-name CN=garnet.local

// after (on Linux)
--cert-file-name /etc/garnet/cert.pfx --cert-password mypassword

if (!string.IsNullOrEmpty(options.CertSubjectName) && !OperatingSystem.IsWindows())
    throw new PlatformNotSupportedException("--cert-subject-name is Windows-only. Use --cert-file-name on this platform.");

When it happens

Trigger: Running Garnet on Linux or macOS with --cert-subject-name set. The check is CertSubjectName != null && !RuntimeInformation.IsOSPlatform(OSPlatform.Windows).

Common situations: 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.

Related errors

• CertFileName and CertSubjectName cannot both be null.
• Cannot use CertFileName with CertSubjectName. Provide only o
• CertificateRefreshFrequency should not be less than 0.
• ClientTargetHost should be provided when ServerCertificateRe
• Unable to load certificate with subject name {subjectName}

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