go-sql-driver/mysql · error

invalid value for TLS config name: %v

Error message

invalid value for TLS config name: %v

What it means

Returned by the `tls` DSN parameter handler when the value is neither a bool (true/false), nor skip-verify/preferred, and also fails url.QueryUnescape. In that branch (dsn.go:659-661) the driver treats the value as the name of a custom TLS config registered via RegisterTLSConfig; a malformed percent-encoded value yields this error.

Source

Thrown at dsn.go:661

			if err != nil {
				return
			}

		// TLS-Encryption
		case "tls":
			boolValue, isBool := readBool(value)
			if isBool {
				if boolValue {
					cfg.TLSConfig = "true"
				} else {
					cfg.TLSConfig = "false"
				}
			} else if vl := strings.ToLower(value); vl == "skip-verify" || vl == "preferred" {
				cfg.TLSConfig = vl
			} else {
				name, err := url.QueryUnescape(value)
				if err != nil {
					return fmt.Errorf("invalid value for TLS config name: %v", err)
				}
				cfg.TLSConfig = name
			}

		// I/O write Timeout
		case "writeTimeout":
			cfg.WriteTimeout, err = time.ParseDuration(value)
			if err != nil {
				return
			}
		case "maxAllowedPacket":
			cfg.MaxAllowedPacket, err = strconv.Atoi(value)
			if err != nil {
				return
			}

		// Connection attributes
		case "connectionAttributes":

View on GitHub (pinned to c426bd9379)

Solutions

1. Use a simple ASCII name for RegisterTLSConfig (e.g. `custom`) and reference it as `?tls=custom`.
2. If the name must contain special characters, URL-encode it with url.QueryEscape when building the DSN.
3. Prefer the Config{TLSConfig:...}.FormatDSN() builder over string concatenation.

Example fix

// before
dsn := "u:p@/db?tls=my%config"
// after
mysql.RegisterTLSConfig("custom", tlscfg)
dsn := "u:p@/db?tls=custom"

switch strings.ToLower(v) {
case "true","false","skip-verify","preferred":
default:
    if _, err := url.QueryUnescape(v); err != nil {
        return errors.New("tls value is invalid")
    }
}

When it happens

Trigger: DSN like `?tls=my%2` or `?tls=100%` where the value is not a recognised keyword and contains an invalid percent-escape sequence. The unescape error is wrapped and returned at dsn.go:661.

Common situations: Naming a custom TLS config with a `%` and forgetting to encode it; mixing encoded/decoded layers when templating DSNs across config files.

Related errors

• invalid value for server pub key name: %v
• invalid value / unknown config name: {cfg.TLSConfig}
• invalid connectionAttributes value: %v
• invalid DSN: did you forget to escape a param value?
• invalid DSN: missing the slash separating the database name

AI-assisted analysis of go-sql-driver/mysql@c426bd9379 (2026-08-04). Data as JSON: /data/errors/4a703ca01f8f6687.json. Report an issue: GitHub.