go-sql-driver/mysql · error

invalid connectionAttributes value: %v

Error message

invalid connectionAttributes value: %v

What it means

Returned when the `connectionAttributes` DSN parameter fails url.QueryUnescape. Connection attributes are key:value pairs sent during the handshake; the driver unescapes the whole value at dsn.go:680. Malformed percent-encoding aborts parsing with this error at dsn.go:682.

Source

Thrown at dsn.go:682

			}

		// 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":
			connectionAttributes, err := url.QueryUnescape(value)
			if err != nil {
				return fmt.Errorf("invalid connectionAttributes value: %v", err)
			}
			cfg.ConnectionAttributes = connectionAttributes

		default:
			// lazy init
			if cfg.Params == nil {
				cfg.Params = make(map[string]string)
			}

			if cfg.Params[key], err = url.QueryUnescape(value); err != nil {
				return
			}
		}
	}

	return
}

View on GitHub (pinned to c426bd9379)

Solutions

1. URL-encode the whole attributes value with url.QueryEscape when building the DSN: e.g. url.QueryEscape("program_name:myapp,program_version:1.0").
2. Keep attribute values free of `%` and other reserved characters.
3. Construct the DSN via Config{ConnectionAttributes:...}.FormatDSN(), which encodes the value for you (dsn.go:331).

Example fix

// before
attr := "app:go-app,coverage:100%"
dsn := "u:p@/db?connectionAttributes=" + attr
// after
attr := "app:go-app,coverage:100%"
dsn := "u:p@/db?connectionAttributes=" + url.QueryEscape(attr)

enc := url.QueryEscape(connectionAttributes)
if _, err := url.QueryUnescape(enc); err != nil {
    return err
}
dsn += "&connectionAttributes=" + enc

When it happens

Trigger: DSN contains `connectionAttributes=...` with a bad percent sequence, e.g. `connectionAttributes=attr1:/unescaped/value` (the `/` is fine but a stray `%` is not) or `connectionAttributes=app:v1%2`. The unescape at dsn.go:680 fails and the error is returned at dsn.go:682.

Common situations: Embedding version strings or file paths that contain `%` without encoding; building the attributes string by hand; a value like `100%` left unescaped.

Related errors

• invalid value for server pub key name: %v
• invalid value for TLS config name: %v
• invalid DSN: did you forget to escape a param value?
• invalid DSN: missing the slash separating the database name
• default addr for network '{cfg.Net}' unknown

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