go-sql-driver/mysql · error

unknown collation: %q

Error message

unknown collation: %q

What it means

Returned during the handshake response (packets.go:348) when the collation DSN parameter names a collation absent from the driver's built-in collations map (which only contains entries with ID < 256) AND a charset is also configured. The driver cannot map the name to a collation ID for the handshake byte. When charset is set the collation is later applied via SET NAMES, but the driver still errors here because the name is unrecognized.

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 c426bd9379)

Solutions

1. Use the exact collation name from the driver's supported set (run SHOW COLLATION and pick one with Id < 256).
2. Remove the collation parameter and rely on charset alone if a specific collation is not required.
3. Correct any spelling/casing mistake in the collation name.

Example fix

// before — misspelled collation
sql.Open("mysql", "user:pass@/db?charset=utf8mb4&collation=utf8mb4_unicde_ci")

// after
sql.Open("mysql", "user:pass@/db?charset=utf8mb4&collation=utf8mb4_unicode_ci")

// The collations map is unexported, so keep a vetted set of supported names
// (those with Id < 256 from SHOW COLLATION) and validate membership:
var supportedCollation = map[string]bool{
    "utf8mb4_general_ci": true, "utf8mb4_unicode_ci": true, "latin1_swedish_ci": true,
}
if cfgCollation != "" && !supportedCollation[cfgCollation] {
    return fmt.Errorf("collation %q is not in the driver's built-in map", cfgCollation)
}

if err := db.Ping(); err != nil {
    if strings.Contains(err.Error(), "unknown collation") {
        // correct or drop the collation parameter in the DSN
    }
}

When it happens

Trigger: DSN contains both charset=utf8mb4&collation=<name> where <name> is misspelled, uses wrong casing, or is a high-ID/MariaDB-specific collation not present in the driver's static map. The else-if branch at packets.go:346 fires only because len(cfg.charsets) > 0.

Common situations: Typo in the collation name (utf8mb4_unicde_ci vs utf8mb4_unicode_ci); using a collation added in a newer server version than the driver's map; copying a collation name from a MariaDB server into a MySQL-targeted DSN.

Related errors

• invalid DSN: interpolateParams can not be used with unsafe c
• invalid max_allowed_packet value (%q): %w
• unsupported protocol version %d. Version %d or higher is req
• 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/61768d23feb34241.json. Report an issue: GitHub.