go-sql-driver/mysql · error

invalid connectionAttributes value

Error message

invalid connectionAttributes value: %v

What it means

The 'connectionAttributes' DSN parameter supplies key-value session attributes sent in the connection handshake. Its value is url.QueryUnescape'd; a malformed percent-escape produces this error wrapping the unescape failure.

Solutions

1. Build the value with url.QueryEscape when constructing the DSN.
2. Use plain ASCII key=value pairs separated by commas.
3. Encode any literal '%' as %25.

Example fix

// before
sql.Open("mysql", "user@tcp(127.0.0.1:3306)/db?connectionAttributes=app%name=svc")
// after
sql.Open("mysql", "user@tcp(127.0.0.1:3306)/db?connectionAttributes=app%25name=svc")

// Validate the attribute value decodes before use.
import "net/url"
if _, err := url.QueryUnescape(connAttrs); err != nil {
    return err
}

null

// connectionAttributes errors surface at DSN parse time.
if _, err := mysql.ParseDSN(dsn); err != nil {
    return err
}

When it happens

Trigger: A DSN like '?connectionAttributes=%ZZ' or any value with a '%' not followed by two hex digits.

Common situations: Programmatically building the attributes string and double-escaping or introducing a stray '%'; copying a value with unencoded special characters.

Related errors

• invalid dbname
• invalid timeTruncate value
• invalid value for server pub key name
• invalid value for TLS config name
• key ' ' is reserved

AI-assisted analysis of go-sql-driver/mysql@03d76c7e07 (2026-08-07). Data as JSON: /api/errors/12af9f9a527b383d. Report an issue: GitHub.

Appendix: 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 03d76c7e07)