temporalio/temporal · error

failed to register tls config: %v

Error message

failed to register tls config: %v

What it means

registerTLSConfig builds a *tls.Config and registers it with the go-sql-driver/mysql driver under the name 'custom' via mysql.RegisterTLSConfig, so connections can select it with a tls=custom connect attribute. This error is returned when the driver refuses the registration — the only documented cause is a nil tls.Config. It fires after the CA/cert files have been successfully loaded, so it almost always indicates a programmatic bug rather than a configuration problem.

Source

Thrown at common/persistence/sql/sqlplugin/mysql/session/session.go:241

	if cfg.TLS.CertFile != "" && cfg.TLS.KeyFile != "" {
		clientCert := make([]tls.Certificate, 0, 1)
		certs, err := tls.LoadX509KeyPair(
			cfg.TLS.CertFile,
			cfg.TLS.KeyFile,
		)
		if err != nil {
			return fmt.Errorf("failed to load tls x509 key pair: %v", err)
		}
		clientCert = append(clientCert, certs)
		tlsConfig.Certificates = clientCert
	}

	// In order to use the TLS configuration you need to register it. Once registered you use it by specifying
	// `tls` in the connect attributes.
	err := mysql.RegisterTLSConfig(customTLSName, tlsConfig)
	if err != nil {
		return fmt.Errorf("failed to register tls config: %v", err)
	}

	if cfg.ConnectAttributes == nil {
		cfg.ConnectAttributes = map[string]string{}
	}

	// If no `tls` connect attribute is provided then we override it to our newly registered tls config automatically.
	// This allows users to simply provide a tls config without needing to remember to also set the connect attribute
	if cfg.ConnectAttributes["tls"] == "" {
		cfg.ConnectAttributes["tls"] = customTLSName
	}

	return nil
}

View on GitHub (pinned to bde624efd1)

Solutions

1. Check that cfg.TLS.Enabled is not being toggled after the tlsConfig is built, which could yield a nil *tls.Config.
2. Inspect go.mod for duplicate/mismatched go-sql-driver/mysql versions (go mod graph | grep mysql) — RegisterTLSConfig rejects nil configs only.
3. Pin a single go-sql-driver/mysql version and rebuild; the underlying driver has not returned other error kinds for this call.
4. Reproduce in isolation: build auth.NewTLSConfigForServer(serverName, enableHostVerification) and pass it to mysql.RegisterTLSConfig to confirm it succeeds.

Example fix

// before (hypothetical nil config path)
tlsConfig := auth.NewTLSConfigForServer(cfg.TLS.ServerName, cfg.TLS.EnableHostVerification)
_ = tlsConfig

// after — fail fast if the config is nil before registering
if tlsConfig == nil {
    return fmt.Errorf("tls config is nil")
}

// Go: ensure a non-nil tls.Config exists before registering
if cfg.TLS != nil && cfg.TLS.Enabled {
    if tlsConfig == nil {
        return fmt.Errorf("tls config must not be nil before RegisterTLSConfig")
    }
}

func hasValidTLSConfig(c *tls.Config) bool { return c != nil }

if err := registerTLSConfig(cfg); err != nil {
    if strings.Contains(err.Error(), "failed to register tls config") {
        logger.DPanic("mysql driver refused TLS registration; check driver version/config", tag.Error(err))
    }
    return err
}

When it happens

Trigger: createConnection -> registerTLSConfig calls mysql.RegisterTLSConfig(customTLSName, tlsConfig) and the driver rejects it because tlsConfig is nil; in practice this happens only if auth.NewTLSConfigForServer unexpectedly returns nil while cfg.TLS.Enabled is true.

Common situations: Running multiple mysql driver versions via dependency skew; a modified fork of the session setup that can pass a nil config; hard-to-reach defensive branch hit during driver upgrades.

Understand the failure class

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

Related errors

• failed to load CA files: %v
• failed to append CA file
• failed to load tls x509 key pair: %v
• only one of keyData or keyFile properties should be specifie
• only one of caData or caFile properties should be specified

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/7ebbfe3d2dfd1efb. Report an issue: GitHub.