go-sql-driver/mysql · error

invalid DSN: interpolateParams can not be used with unsafe c

Error message

invalid DSN: interpolateParams can not be used with unsafe collations

What it means

normalize() refuses the combination interpolateParams=true with a collation on the unsafeCollations denylist (collations.go:253: big5, sjis, gbk, cp932, gb18030 variants). These multibyte collations can carry a 0x5c ('\') in a trailing byte, which makes client-interpolated parameter values injectable, so the driver aborts at dsn.go:174 before opening.

Source

Thrown at dsn.go:32

	"crypto/rsa"
	"crypto/tls"
	"errors"
	"fmt"
	"maps"
	"math/big"
	"net"
	"net/url"
	"sort"
	"strconv"
	"strings"
	"time"
)

var (
	errInvalidDSNUnescaped       = errors.New("invalid DSN: did you forget to escape a param value?")
	errInvalidDSNAddr            = errors.New("invalid DSN: network address not terminated (missing closing brace)")
	errInvalidDSNNoSlash         = errors.New("invalid DSN: missing the slash separating the database name")
	errInvalidDSNUnsafeCollation = errors.New("invalid DSN: interpolateParams can not be used with unsafe collations")
)

// Config is a configuration parsed from a DSN string.
// If a new Config is created instead of being parsed from a DSN string,
// the NewConfig function should be used, which sets default values.
type Config struct {
	// non boolean fields

	User                 string            // Username
	Passwd               string            // Password (requires User)
	Net                  string            // Network (e.g. "tcp", "tcp6", "unix". default: "tcp")
	Addr                 string            // Address (default: "127.0.0.1:3306" for "tcp" and "/tmp/mysql.sock" for "unix")
	DBName               string            // Database name
	Params               map[string]string // Connection parameters
	ConnectionAttributes string            // Connection Attributes, comma-delimited string of user-defined "key:value" pairs
	Collation            string            // Connection collation. When set, this will be set in SET NAMES <charset> COLLATE <collation> query
	Loc                  *time.Location    // Location for time.Time values
	MaxAllowedPacket     int               // Max packet size allowed

View on GitHub (pinned to c426bd9379)

Solutions

1. Keep interpolateParams and switch the collation to a safe one (e.g. utf8mb4_general_ci or utf8mb4_0900_ai_ci).
2. Keep the unsafe collation and disable interpolateParams; the driver will use server-side prepared statements instead.
3. Leave cfg.Collation empty and rely on a safe server-default collation.

Example fix

// before
dsn := "user@tcp(host:3306)/db?interpolateParams=true&collation=gbk_chinese_ci"
// after
dsn := "user@tcp(host:3306)/db?interpolateParams=true&collation=utf8mb4_0900_ai_ci"

var unsafeCollations = map[string]bool{
    "big5_chinese_ci": true, "sjis_japanese_ci": true, "gbk_chinese_ci": true,
    "big5_bin": true, "gb2312_bin": true, "gbk_bin": true, "sjis_bin": true,
    "cp932_japanese_ci": true, "cp932_bin": true,
    "gb18030_chinese_ci": true, "gb18030_bin": true, "gb18030_unicode_520_ci": true,
}
func safeCombo(interpolate bool, collation string) bool {
    return !(interpolate && collation != "" && unsafeCollations[collation])
}

if _, err := mysql.ParseDSN(dsn); err != nil && strings.Contains(err.Error(), "unsafe collations") {
    // drop interpolateParams or switch collation to utf8mb4_0900_ai_ci
}

When it happens

Trigger: A DSN like 'user@tcp(host)/db?interpolateParams=true&collation=gbk_chinese_ci', or a Config with InterpolateParams=true and Collation='big5_bin', passed to sql.Open/NewConnector.

Common situations: Enabling interpolateParams for performance on a legacy Asian-language MySQL (gbk/big5/sjis); porting a DSN from a utf8 (safe) project to one using a multibyte Asian collation; CI passes with utf8mb4 but production uses sjis.

Related errors

• invalid bool value: {value}
• 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
• invalid value / unknown config name: {cfg.TLSConfig}

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