go-sql-driver/mysql · error

unknown collation

Error message

unknown collation: %q

What it means

When both a charset and a collation are configured, the driver validates the collation name against its built-in collation table while building the handshake response. An unrecognized collation cannot be set safely via 'SET NAMES <charset> COLLATE <collation>', so the driver rejects it. (Without a charset, an unknown collation is silently passed through.)

Solutions

1. Use a valid collation name from the driver's table, e.g. utf8mb4_general_ci or utf8mb4_0900_ai_ci.
2. Remove the collation parameter to let the charset pick its default collation.
3. Cross-check the exact spelling/case against the server's 'SHOW COLLATION' output.

Example fix

// before
sql.Open("mysql", "user@tcp(127.0.0.1:3306)/db?charset=utf8mb4&collation=utf8mb4_general")
// after
sql.Open("mysql", "user@tcp(127.0.0.1:3306)/db?charset=utf8mb4&collation=utf8mb4_general_ci")

// Validate the collation name against the driver's known set (mirror collations.go).
if _, ok := knownCollations[collation]; !ok {
    return fmt.Errorf("unknown collation: %s", collation)
}

null

// Unknown-collation errors surface at handshake (first query/Ping).
if err := db.Ping(); err != nil {
    if strings.Contains(err.Error(), "unknown collation") {
        // fix the DSN collation and reconnect
    }
}

When it happens

Trigger: A DSN like '?charset=utf8mb4&collation=utf8mb4_bogus', or using the mysql.Charset("utf8mb4","bogus") option, where the collation is not in the driver's collations map. Typos, case differences, or a collation only a newer server supports.

Common situations: Typo in the collation name; collation introduced in a newer MySQL not yet in the driver's table; mixing up charset and collation option names.

Related errors

• invalid connectionAttributes value
• invalid dbname
• invalid timeTruncate value
• key ' ' is reserved
• argument count mismatch

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

Appendix: source

Thrown at packets.go:348

		return err
	}
	_ = data[4*3+23] // boundery check

	// clientCapabilities [32 bit]
	binary.LittleEndian.PutUint32(data[4:], uint32(mc.capabilities))

	// MaxPacketSize [32 bit] (none)
	binary.LittleEndian.PutUint32(data[8:], 0)

	// Collation ID [1 byte]
	data[12] = defaultCollationID
	if cname := mc.cfg.Collation; cname != "" {
		colID, ok := collations[cname]
		if ok {
			data[12] = colID
		} else if len(mc.cfg.charsets) > 0 {
			// When cfg.charset is set, the collation is set by `SET NAMES <charset> COLLATE <collation>`.
			return fmt.Errorf("unknown collation: %q", cname)
		}
	}

	// Filler [23 bytes] (all 0x00)
	// or filler 19bytes + mariadb extCapabilities
	pos := 13
	if mc.capabilities&clientMySQL == 0 {
		for ; pos < 13+19; pos++ {
			data[pos] = 0
		}
		// MariaDB Extended Capabilities
		binary.LittleEndian.PutUint32(data[13+19:], uint32(mc.extCapabilities))
	} else {
		for ; pos < 13+23; pos++ {
			data[pos] = 0
		}
	}

View on GitHub (pinned to 03d76c7e07)