microsoft/garnet · error · GarnetException

CertificateRefreshFrequency should not be less than 0.

Error message

CertificateRefreshFrequency should not be less than 0.

What it means

Garnet validates that CertificateRefreshFrequency is non-negative. This value controls how often the server re-reads the certificate from disk or the Windows store to pick up rotations. A negative value would cause the refresh timer to behave incorrectly. The check fires in GetSslServerAuthenticationOptions() before the ServerCertificateSelector is constructed.

Source

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

            }

            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
            {
                ClientCertificateRequired = ClientCertificateRequired,
                CertificateRevocationCheckMode = CertificateRevocationCheckMode,
                RemoteCertificateValidationCallback = ValidateClientCertificateCallback(IssuerCertificatePath),
                ServerCertificateSelectionCallback = (sender, hostName) =>
                {

View on GitHub (pinned to 951b0fc683)

Solutions

1. Set --cert-refresh-frequency to 0 (disables refresh) or a positive value in seconds (e.g., --cert-refresh-frequency 3600).
2. Remove the flag to use the default value.
3. Check the config file for stray negative signs or unquoted values that parse incorrectly.

Example fix

// before
--cert-refresh-frequency -1

// after
--cert-refresh-frequency 0

if (options.CertificateRefreshFrequency < 0)
    throw new ArgumentOutOfRangeException(nameof(options.CertificateRefreshFrequency), "Must be >= 0.");

When it happens

Trigger: Setting --cert-refresh-frequency to a negative value. For example, --cert-refresh-frequency -1 or a misconfigured environment variable that resolves to a negative number.

Common situations: Config file typo producing a negative value; environment variable defaulting to -1 as a sentinel that Garnet does not recognize; parsing error where a time unit is stripped leaving a bare negative number.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• CertFileName and CertSubjectName cannot both be null.
• Cannot use CertFileName with CertSubjectName. Provide only o
• CertSubjectName is supported only on Windows.
• 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/9cef122df2e834fa. Report an issue: GitHub.