microsoft/garnet · error · GarnetException

Cannot use CertFileName with CertSubjectName. Provide only o

Error message

Cannot use CertFileName with CertSubjectName. Provide only one of them.

What it means

Garnet's TLS configuration rejects specifying both CertFileName (file-based cert) and CertSubjectName (Windows cert store lookup) simultaneously. Only one certificate source is allowed to avoid ambiguity about which certificate to use. The check fires in GetSslServerAuthenticationOptions() after the null-check.

Source

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

            errorMessage = null;
            CertFileName = certFileName;
            CertPassword = certPassword;
            TlsServerOptions = GetSslServerAuthenticationOptions();
            return true;
        }

        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();

View on GitHub (pinned to 951b0fc683)

Solutions

1. Remove --cert-subject-name and keep only --cert-file-name (and --cert-password).
2. Remove --cert-file-name and keep only --cert-subject-name (Windows only).
3. Check environment variables and config files for stale certificate settings that conflict with command-line flags.

Example fix

// before
--cert-file-name /path/cert.pfx --cert-subject-name CN=mycert

// after
--cert-file-name /path/cert.pfx --cert-password mypassword

if (!string.IsNullOrEmpty(options.CertFileName) && !string.IsNullOrEmpty(options.CertSubjectName))
    throw new InvalidOperationException("Specify only one of --cert-file-name or --cert-subject-name, not both.");

When it happens

Trigger: Providing both --cert-file-name and --cert-subject-name on the command line or in the config file. For example: --cert-file-name /path/cert.pfx --cert-subject-name CN=mycert.

Common situations: Copy-pasting a config template that had both options listed (one commented, both uncommented by mistake); migrating from file-based to store-based certs and leaving the old setting; environment variable for one cert source still set while the other is explicitly configured.

Related errors

• CertFileName and CertSubjectName cannot both be null.
• ClientTargetHost should be provided when ServerCertificateRe
• Unable to load certificate with subject name {subjectName}
• CertSubjectName is supported only on Windows.
• CertificateRefreshFrequency should not be less than 0.

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