{"record":{"id":"7ebbfe3d2dfd1efb","repo":"temporalio/temporal","slug":"failed-to-register-tls-config-v","errorCode":null,"errorMessage":"failed to register tls config: %v","messagePattern":"failed to register tls config: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/persistence/sql/sqlplugin/mysql/session/session.go","lineNumber":241,"sourceCode":"\n\tif cfg.TLS.CertFile != \"\" && cfg.TLS.KeyFile != \"\" {\n\t\tclientCert := make([]tls.Certificate, 0, 1)\n\t\tcerts, err := tls.LoadX509KeyPair(\n\t\t\tcfg.TLS.CertFile,\n\t\t\tcfg.TLS.KeyFile,\n\t\t)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to load tls x509 key pair: %v\", err)\n\t\t}\n\t\tclientCert = append(clientCert, certs)\n\t\ttlsConfig.Certificates = clientCert\n\t}\n\n\t// In order to use the TLS configuration you need to register it. Once registered you use it by specifying\n\t// `tls` in the connect attributes.\n\terr := mysql.RegisterTLSConfig(customTLSName, tlsConfig)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to register tls config: %v\", err)\n\t}\n\n\tif cfg.ConnectAttributes == nil {\n\t\tcfg.ConnectAttributes = map[string]string{}\n\t}\n\n\t// If no `tls` connect attribute is provided then we override it to our newly registered tls config automatically.\n\t// This allows users to simply provide a tls config without needing to remember to also set the connect attribute\n\tif cfg.ConnectAttributes[\"tls\"] == \"\" {\n\t\tcfg.ConnectAttributes[\"tls\"] = customTLSName\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":223,"sourceCodeEnd":256,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/persistence/sql/sqlplugin/mysql/session/session.go#L223-L256","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check that cfg.TLS.Enabled is not being toggled after the tlsConfig is built, which could yield a nil *tls.Config.","Inspect go.mod for duplicate/mismatched go-sql-driver/mysql versions (go mod graph | grep mysql) — RegisterTLSConfig rejects nil configs only.","Pin a single go-sql-driver/mysql version and rebuild; the underlying driver has not returned other error kinds for this call.","Reproduce in isolation: build auth.NewTLSConfigForServer(serverName, enableHostVerification) and pass it to mysql.RegisterTLSConfig to confirm it succeeds."],"exampleFix":"// before (hypothetical nil config path)\ntlsConfig := auth.NewTLSConfigForServer(cfg.TLS.ServerName, cfg.TLS.EnableHostVerification)\n_ = tlsConfig\n\n// after — fail fast if the config is nil before registering\nif tlsConfig == nil {\n    return fmt.Errorf(\"tls config is nil\")\n}","handlingStrategy":"try-catch","validationCode":"// Go: ensure a non-nil tls.Config exists before registering\nif cfg.TLS != nil && cfg.TLS.Enabled {\n    if tlsConfig == nil {\n        return fmt.Errorf(\"tls config must not be nil before RegisterTLSConfig\")\n    }\n}","typeGuard":"func hasValidTLSConfig(c *tls.Config) bool { return c != nil }","tryCatchPattern":"if err := registerTLSConfig(cfg); err != nil {\n    if strings.Contains(err.Error(), \"failed to register tls config\") {\n        logger.DPanic(\"mysql driver refused TLS registration; check driver version/config\", tag.Error(err))\n    }\n    return err\n}","preventionTips":["Keep a single go-sql-driver/mysql version in go.mod (go mod tidy; check go mod graph).","Never construct SQL config with TLS.Enabled=true but a nil/empty TLS section.","Add a startup smoke test that connects with TLS before marking the service ready."],"tags":["mysql","tls","driver","configuration"],"backgroundTag":"tls-config-registration-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}