go-sql-driver/mysql · error

invalid value for server pub key name: %v

Error message

invalid value for server pub key name: %v

What it means

Returned when the `serverPubKey` DSN parameter fails URL-unescaping. serverPubKey references a name previously registered with mysql.RegisterServerPubKey, used during sha256_password / caching_sha2_password RSA exchange. The driver runs url.QueryUnescape on the value at dsn.go:632 and surfaces the unescape error if the value contains malformed percent-encoding.

Source

Thrown at dsn.go:632

		case "readTimeout":
			cfg.ReadTimeout, err = time.ParseDuration(value)
			if err != nil {
				return
			}

		// Reject read-only connections
		case "rejectReadOnly":
			var isBool bool
			cfg.RejectReadOnly, isBool = readBool(value)
			if !isBool {
				return errors.New("invalid bool value: " + value)
			}

		// Server public key
		case "serverPubKey":
			name, err := url.QueryUnescape(value)
			if err != nil {
				return fmt.Errorf("invalid value for server pub key name: %v", err)
			}
			cfg.ServerPubKey = name

		// Strict mode
		case "strict":
			panic("strict mode has been removed. See https://github.com/go-sql-driver/mysql/wiki/strict-mode")

		// Dial Timeout
		case "timeout":
			cfg.Timeout, err = time.ParseDuration(value)
			if err != nil {
				return
			}

		// TLS-Encryption
		case "tls":
			boolValue, isBool := readBool(value)
			if isBool {

View on GitHub (pinned to c426bd9379)

Solutions

1. URL-encode the value when building the DSN: `serverPubKey=` + url.QueryEscape(name).
2. Use plain ASCII alphanumeric names for registered public keys so no escaping is needed.
3. Build the DSN from a Config struct via cfg.FormatDSN() instead of hand-concatenating strings.

Example fix

// before
name := "my%key"
dsn := fmt.Sprintf("u:p@/db?serverPubKey=%s", name)
// after
name := "my%key"
dsn := fmt.Sprintf("u:p@/db?serverPubKey=%s", url.QueryEscape(name))

if _, err := url.QueryUnescape(serverPubKeyRaw); err != nil {
    return fmt.Errorf("serverPubKey is not URL-safe: %w", err)
}
dsn += "&serverPubKey=" + url.QueryEscape(name)

When it happens

Trigger: DSN contains `serverPubKey=<value>` where value has a bad percent sequence such as `%` not followed by two hex digits (e.g. `serverPubKey=key%2`, `serverPubKey=100%done`). The unescape at dsn.go:630 returns an error which is wrapped and returned at dsn.go:632.

Common situations: Embedding a name containing a literal `%` character without encoding it; constructing the DSN via string concatenation instead of using the Config.FormatDSN builder; copy-paste from a URL where the value was already partly encoded.

Related errors

• invalid value for TLS config 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/c610f430788a64bd.json. Report an issue: GitHub.