{"id":"c69fdd0bbeba1e72","repo":"go-sql-driver/mysql","slug":"invalid-value-unknown-config-name-cfg-tlsconfi","errorCode":null,"errorMessage":"invalid value / unknown config name: {cfg.TLSConfig}","messagePattern":"invalid value / unknown config name: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"dsn.go","lineNumber":210,"sourceCode":"\t} else if cfg.Net == \"tcp\" {\n\t\tcfg.Addr = ensureHavePort(cfg.Addr)\n\t}\n\n\tif cfg.TLS == nil {\n\t\tswitch cfg.TLSConfig {\n\t\tcase \"false\", \"\":\n\t\t\t// don't set anything\n\t\tcase \"true\":\n\t\t\tcfg.TLS = &tls.Config{}\n\t\tcase \"skip-verify\":\n\t\t\tcfg.TLS = &tls.Config{InsecureSkipVerify: true}\n\t\tcase \"preferred\":\n\t\t\tcfg.TLS = &tls.Config{InsecureSkipVerify: true}\n\t\t\tcfg.AllowFallbackToPlaintext = true\n\t\tdefault:\n\t\t\tcfg.TLS = getTLSConfigClone(cfg.TLSConfig)\n\t\t\tif cfg.TLS == nil {\n\t\t\t\treturn errors.New(\"invalid value / unknown config name: \" + cfg.TLSConfig)\n\t\t\t}\n\t\t}\n\t}\n\n\tif cfg.TLS != nil && cfg.TLS.ServerName == \"\" && !cfg.TLS.InsecureSkipVerify {\n\t\thost, _, err := net.SplitHostPort(cfg.Addr)\n\t\tif err == nil {\n\t\t\tcfg.TLS.ServerName = host\n\t\t}\n\t}\n\n\tif cfg.ServerPubKey != \"\" {\n\t\tcfg.pubKey = getServerPubKey(cfg.ServerPubKey)\n\t\tif cfg.pubKey == nil {\n\t\t\treturn errors.New(\"invalid value / unknown server pub key name: \" + cfg.ServerPubKey)\n\t\t}\n\t}\n","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/go-sql-driver/mysql/blob/c426bd93799de0f0e094c8f0582872c529d0ed0a/dsn.go#L192-L228","documentation":"normalize() resolves cfg.TLSConfig against the reserved words 'false'/'', 'true', 'skip-verify', 'preferred', then falls back to the registry populated by RegisterTLSConfig. If the key is not reserved and not registered, getTLSConfigClone returns nil and the driver returns 'invalid value / unknown config name' at dsn.go:210.","triggerScenarios":"A DSN with '?tls=custom' without a prior mysql.RegisterTLSConfig('custom', &tls.Config{...}) call; or the key was registered under a different name, or deregistered before connect.","commonSituations":"TLS registration code in main.go but the DSN is parsed earlier (init/test); typo between the RegisterTLSConfig key and the DSN; trying to register a reserved word ('true'/'skip-verify'/'preferred') which RegisterTLSConfig rejects; registration in a different process than the one opening the connection.","solutions":["Call mysql.RegisterTLSConfig('custom', &tls.Config{...}) before sql.Open/ParseDSN, in the same process.","Verify the key string matches exactly (case, spelling) between RegisterTLSConfig and the DSN.","Use a built-in mode ('true', 'skip-verify', 'preferred') instead of a custom key when you do not need a custom tls.Config.","If you set cfg.TLS directly on the Config, the TLSConfig-name lookup is skipped entirely."],"exampleFix":"// before\ndb, _ := sql.Open(\"mysql\", \"user@tcp(host:3306)/db?tls=custom\")\n// after\nmysql.RegisterTLSConfig(\"custom\", &tls.Config{RootCAs: rootCAs, Certificates: certs})\ndb, _ := sql.Open(\"mysql\", \"user@tcp(host:3306)/db?tls=custom\")","handlingStrategy":"validation","validationCode":"// Verify the key is registered (or a reserved word) before opening.\nfunc tlsKeyKnown(key string) bool {\n    switch key { case \"\", \"false\", \"true\", \"skip-verify\", \"preferred\": return true }\n    // reflect on the registry is not exported; simplest: keep your own set of registered keys\n    return false // replace with your app's tracking of registered names\n}","typeGuard":null,"tryCatchPattern":"if _, err := mysql.ParseDSN(dsn); err != nil && strings.Contains(err.Error(), \"unknown config name\") {\n    // register the TLS config under the right key, then retry\n}","preventionTips":["Register every custom TLS config in a single init() that runs before any sql.Open.","Centralize DSN/TLS construction in one package so registration order is obvious.","Prefer the built-in 'preferred'/'skip-verify'/'true' modes when a custom tls.Config is not required."],"tags":["go","mysql","tls","dsn","config"],"analyzedSha":"c426bd93799de0f0e094c8f0582872c529d0ed0a","analyzedAt":"2026-08-04T21:52:59.219Z","schemaVersion":2}