microsoft/garnet · error · ArgumentException

Unable to load certificate with subject name {subjectName}

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.

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)

Solutions

1. Verify the certificate exists in LocalMachine\My by running 'certutil -store My' or PowerShell 'Get-ChildItem Cert:\LocalMachine\My'.
2. Install the certificate with the correct subject name into the LocalMachine\My store.
3. Switch to --cert-file-name with a PFX file path instead of subject-name lookup if the cert store is not available.
4. 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 ********

// 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 { 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; }

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

• CertFileName and CertSubjectName cannot both be null.
• Cannot use CertFileName with CertSubjectName. Provide only o
• ClientTargetHost should be provided when ServerCertificateRe
• 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/d8ff9a0aa9b3f2d6. Report an issue: GitHub.