Hive two-way TLS requires sslKeyStore or a client certificat

Error message

Hive two-way TLS requires sslKeyStore or a client certificate

What it means

This error is thrown when the Hive connection string enables two-way (mutual) TLS via the 'twoway' parameter but provides neither a keystore location nor a client certificate loaded into the TLS config. Mutual TLS requires the client to present a certificate to the server; without one the TLS handshake cannot succeed, so the driver fails fast at config time. It validates that either 'sslKeyStore' was supplied or certificates were already appended to config.Certificates.

Source

Thrown at agents/drivers/argo-go/config.go:1110

	}
	keyStoreLocation := parameter(values, "sslkeystore")
	if keyStoreLocation != "" {
		if parameter(values, "keystorepassword") == "" && credentialProviderPath != "" {
			return nil, errors.New("Hive storePasswordPath uses the Java Hadoop credential-provider format; configure keyStorePassword explicitly for the native agent")
		}
		certificate, err := loadClientKeyStore(
			keyStoreLocation,
			parameter(values, "keystorepassword"),
			parameter(values, "keystoretype"),
		)
		if err != nil {
			return nil, fmt.Errorf("load Hive keystore: %w", err)
		}
		config.Certificates = append(config.Certificates, certificate)
	}
	if parameterBool(values, "twoway") {
		if keyStoreLocation == "" && len(config.Certificates) == 0 {
			return nil, errors.New("Hive two-way TLS requires sslKeyStore or a client certificate")
		}
		if trustStoreLocation == "" && config.RootCAs == nil {
			return nil, errors.New("Hive two-way TLS requires sslTrustStore or a CA certificate")
		}
	}
	return config, nil
}

func parameter(values map[string]string, key string) string {
	for candidate, value := range values {
		if strings.EqualFold(strings.TrimSpace(candidate), key) {
			return strings.TrimSpace(value)
		}
	}
	return ""
}

func parameterBool(values map[string]string, key string) bool {

View on GitHub (pinned to c0390bff16)

Solutions

Set sslKeyStore (and sslKeyStorePassword) in the connection config pointing to a valid PKCS12/JKS keystore containing the client certificate
Provide a client certificate another way so config.Certificates is non-empty before the twoway check
If mutual TLS is not actually required by the server, remove the twoway parameter to use one-way TLS

Example fix

// before
dsn := "hive://user@hs2.example.com:10000/default?twoway=true&sslTrustStore=/etc/ssl/truststore.p12"
// after
dsn := "hive://user@hs2.example.com:10000/default?twoway=true&sslKeyStore=/etc/ssl/keystore.p12&sslKeyStorePassword=secret&sslTrustStore=/etc/ssl/truststore.p12"

Defensive patterns

Strategy: validation

Validate before calling

if strings.EqualFold(values["twoway"], "true") && values["sslKeyStore"] == "" {
	return errors.New("twoway=true requires sslKeyStore (and password)")
}

Type guard

func hasClientCert(values map[string]string) bool {
	return values["sslKeyStore"] != "" || values["sslKeyStorePassword"] != ""
}

Prevention

Always pair twoway=true with both sslKeyStore and sslKeyStorePassword
Verify the keystore file exists and is readable before connecting
Test the TLS handshake with openssl s_client -cert when provisioning new client certs

When it happens

Trigger: Calling the driver's Open/Connect with a connection config containing twoway=true (or twoway set truthy) while sslKeyStore is empty/missing and no client certificate was loaded from a keystore (keystore load failed silently or was skipped).

Common situations: Users enable Hive two-way SSL but forget sslKeyStorePassword so the keystore fails to load; users copy a one-way TLS URL and add twoway without adding client cert material; clusters switched to mutual TLS require client certs that were never provisioned.

Understand the failure class

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

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/83251ba3f8137137. Report an issue: GitHub.