microsoft/garnet · error · GarnetException

ClientTargetHost should be provided when ServerCertificateRe

Error message

ClientTargetHost should be provided when ServerCertificateRequired is enabled

What it means

Garnet's TLS client options require a ClientTargetHost (the SNI hostname) when ServerCertificateRequired is enabled. The target host is needed for TLS SNI extension and for remote certificate validation callbacks. Without it, the client cannot properly authenticate or validate the server. This check is in GetSslClientAuthenticationOptions(), which configures the server's own outbound TLS client (used for replication/clustering over TLS).

Source

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

            return new SslServerAuthenticationOptions
            {
                ClientCertificateRequired = ClientCertificateRequired,
                CertificateRevocationCheckMode = CertificateRevocationCheckMode,
                RemoteCertificateValidationCallback = ValidateClientCertificateCallback(IssuerCertificatePath),
                ServerCertificateSelectionCallback = (sender, hostName) =>
                {
                    return serverCertificateSelector.GetSslServerCertificate();
                }
            };
        }

        SslClientAuthenticationOptions GetSslClientAuthenticationOptions()
        {
            if (ServerCertificateRequired && string.IsNullOrEmpty(ClientTargetHost))
            {
                logger?.LogError("ClientTargetHost should be provided when ServerCertificateRequired is enabled");
                throw new GarnetException("ClientTargetHost should be provided when ServerCertificateRequired is enabled");
            }
            return new SslClientAuthenticationOptions
            {
                TargetHost = ClientTargetHost,
                AllowRenegotiation = false,
                CertificateRevocationCheckMode = CertificateRevocationCheckMode,
                RemoteCertificateValidationCallback = ValidateServerCertificateCallback(ClientTargetHost, IssuerCertificatePath),
                // We use the same server certificate selector for the server's own client as well
                LocalCertificateSelectionCallback = (object sender, string targetHost, X509CertificateCollection localCertificates, X509Certificate remoteCertificate, string[] acceptableIssuers) =>
                {
                    return serverCertificateSelector.GetSslServerCertificate();
                }
            };
        }

        /// <summary>
        /// Callback to verify the TLS certificate
        /// </summary>

View on GitHub (pinned to 951b0fc683)

Solutions

1. Set --client-target-host <hostname> to the TLS SNI name of the peer server.
2. Disable --server-certificate-required if the server does not need to present a client certificate to peers.
3. Ensure the hostname matches the certificate's CN or SAN on the remote server.

Example fix

// before
--server-certificate-required

// after
--server-certificate-required --client-target-host garnet-peer.internal

if (options.ServerCertificateRequired && string.IsNullOrEmpty(options.ClientTargetHost))
    throw new InvalidOperationException("--client-target-host is required when --server-certificate-required is enabled.");

When it happens

Trigger: Configuring TLS with ServerCertificateRequired=true but ClientTargetHost empty/null. This occurs when mutual TLS is enabled (the server acts as a TLS client to peers) but no target hostname is specified.

Common situations: Enabling mTLS for cluster replication without setting the peer hostname; config template that enables ServerCertificateRequired but leaves ClientTargetHost commented out; environment variable for the target host not set in production.

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
• 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/d0c23354172cd8eb. Report an issue: GitHub.