microsoft/garnet · error · ArgumentException

Unable to load certificate with subject name

Error message

Unable to load certificate with subject name {subjectName}

What it means

Garnet's CertificateUtils searches the Windows certificate store (LocalMachine\My) by subject name using X509FindType.FindBySubjectName. If zero certificates match, it throws. Note that the search uses validOnly=false, so expired certs are included — the error means no cert with that subject name exists at all. If multiple match, the one with the latest NotAfter date is selected.

Solutions

Verify the certificate exists in LocalMachine\My by running 'certutil -store My' or PowerShell 'Get-ChildItem Cert:\LocalMachine\My'.
Install the certificate with the correct subject name into the LocalMachine\My store.
Switch to --cert-file-name with a PFX file path instead of subject-name lookup if the cert store is not available.
Check for trailing spaces or case differences in the subject name parameter.

Example fix

// before
--cert-subject-name garnet.local

// after (fix the name to match the CN in the store)
--cert-subject-name CN=garnet.local
// or use a file instead
--cert-file-name /path/to/cert.pfx --cert-password ********

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check certificate existence (Windows)
using var store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
store.Open(OpenFlags.ReadOnly);
var found = store.Certificates.Find(X509FindType.FindBySubjectName, subjectName, false);
if (found.Count == 0) throw new FileNotFoundException($"No certificate with subject '{subjectName}' in LocalMachine\\My.");

Try / catch

try { var cert = CertificateUtils.GetCertificate(subjectName); }
catch (ArgumentException ex) when (ex.Message.Contains("Unable to load certificate"))
{ logger.LogError("Certificate not found for subject {Subject}. Install it or switch to --cert-file-name.", subjectName); throw; }

Prevention

Verify certificate existence with certutil or PowerShell before starting the server.
Use --cert-file-name for cross-platform deployments to avoid store dependency.
Document the exact subject name (including CN= prefix if needed) in deployment runbooks.

When it happens

Trigger: Calling GetSslServerCertificate() or constructing ServerCertificateSelector with a CertSubjectName that does not match any certificate in the LocalMachine\My store. The subject name match is by name string, not thumbprint.

Common situations: Typo in the certificate subject name; certificate installed in CurrentUser\My instead of LocalMachine\My; certificate installed under a different subject name (CN mismatch); development machine without the production cert; cert was revoked/removed.

Understand the failure class

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

Related errors

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

Appendix: source

Thrown at libs/server/TLS/CertificateUtils.cs:43

        /// <param name="subjectName"></param>
        /// <returns></returns>
        /// <exception cref="ArgumentException"></exception>
        public static X509Certificate2 GetMachineCertificateBySubjectName(string subjectName)
        {
            X509Store store = null;
            X509Certificate2 certificate;

            try
            {
                store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
                store.Open(OpenFlags.ReadOnly);

                var certificateCollection = store.Certificates
                    .Find(X509FindType.FindBySubjectName, subjectName, false);

                if (certificateCollection.Count <= 0)
                {
                    throw new ArgumentException(
                        $"Unable to load certificate with subject name {subjectName}");
                }

                var latestMatchingCert = certificateCollection.OfType<X509Certificate2>().OrderByDescending(cert => cert.NotAfter).First();
                certificate = new X509Certificate2(latestMatchingCert);
            }
            finally
            {
                store?.Close();
            }

            return certificate;
        }


        /// <summary>
        /// Gets machine certificate by file name. The certificate format (PKCS#12/PFX or PEM) is
        /// detected from the file's contents rather than trusted from its extension.

View on GitHub (pinned to 951b0fc683)