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

With two-way (mutual) TLS enabled via the 'twoway' parameter, the driver requires a client identity: either an sslKeyStore or a client certificate loaded into config.Certificates. If both are absent, the client would present no certificate and the server-side mTLS handshake would fail, so validation fails early.

Source

Thrown at agents/drivers/hive-go/config.go:1113

	}
	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 ClientCertPath and ClientKeyPath to the client cert/key pair.
Set sslKeyStore (with keystorepassword) to supply a client identity.
Remove twoway=true if the server does not actually require client certificates.

Example fix

// before
// twoway=true, sslTrustStore=/etc/certs/ca.pem
// after
// twoway=true, sslTrustStore=/etc/certs/ca.pem, ClientCertPath=/etc/certs/client.pem, ClientKeyPath=/etc/certs/client.key

Defensive patterns

Strategy: validation

Validate before calling

if params["twoway"] == "true" || params["twoway"] == "1" {
	if params["sslkeystore"] == "" && params.ClientCertPath == "" {
		return fmt.Errorf("two-way TLS needs sslKeyStore or a client certificate")
	}
}

Prevention

When enabling twoway, configure all four pieces: client identity, key password, trust store, CA
Template mTLS configs as one unit to avoid partial setups
Test the handshake with openssl s_client before deploying

When it happens

Trigger: Setting twoway=true while sslKeyStore is empty, no sslKeyStore loaded, and no ClientCertPath/ClientKeyPath pair provided.

Common situations: Enabling mTLS on the server but only configuring the trust store (CA) on the client; forgetting the client certificate after turning on 'twoway' to debug server-cert issues; stripped-down config templates omitting client credentials.

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/93795038f02c5874. Report an issue: GitHub.