microsoft/garnet · error · GarnetException

CertFileName and CertSubjectName cannot both be null.

Error message

CertFileName and CertSubjectName cannot both be null.

What it means

Garnet's TLS configuration requires exactly one certificate source. When both CertFileName and CertSubjectName are null, GetSslServerAuthenticationOptions() throws because it cannot create an SSL server without a certificate. This is a hard prerequisite for TLS-enabled operation.

Source

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

            {
                errorMessage = "Cannot provide null cert-file-name.";
                logger?.LogError("Cannot provide null cert-file-name.");
                return false;
            }

            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.");

View on GitHub (pinned to 951b0fc683)

Solutions

1. Provide --cert-file-name <path> with --cert-password <password> for a PFX/PEM file.
2. Provide --cert-subject-name <name> for Windows certificate store lookup (Windows only).
3. Ensure the config file or environment variable supplying the cert name is correctly set and not empty.

Example fix

// before
--cert-file-name "" --cert-subject-name ""

// after
--cert-file-name /etc/garnet/cert.pfx --cert-password mypassword

if (string.IsNullOrEmpty(options.CertFileName) && string.IsNullOrEmpty(options.CertSubjectName))
    throw new InvalidOperationException("TLS requires either --cert-file-name or --cert-subject-name.");

When it happens

Trigger: Constructing GarnetTlsOptions or calling GetSslServerAuthenticationOptions() when neither --cert-file-name nor --cert-subject-name was provided. Occurs when TLS is enabled (the options object is constructed) but no certificate source is configured.

Common situations: Enabling TLS via --auth or other flags but forgetting to specify the certificate; config file with a commented-out cert line; environment variable for cert name not set in the deployment.

Related errors

• Cannot use CertFileName with CertSubjectName. Provide only o
• 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/88ffcdfee0d41f03. Report an issue: GitHub.