{"id":"61768d23feb34241","repo":"go-sql-driver/mysql","slug":"unknown-collation-q","errorCode":null,"errorMessage":"unknown collation: %q","messagePattern":"unknown collation: %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packets.go","lineNumber":348,"sourceCode":"\t\treturn err\n\t}\n\t_ = data[4*3+23] // boundery check\n\n\t// clientCapabilities [32 bit]\n\tbinary.LittleEndian.PutUint32(data[4:], uint32(mc.capabilities))\n\n\t// MaxPacketSize [32 bit] (none)\n\tbinary.LittleEndian.PutUint32(data[8:], 0)\n\n\t// Collation ID [1 byte]\n\tdata[12] = defaultCollationID\n\tif cname := mc.cfg.Collation; cname != \"\" {\n\t\tcolID, ok := collations[cname]\n\t\tif ok {\n\t\t\tdata[12] = colID\n\t\t} else if len(mc.cfg.charsets) > 0 {\n\t\t\t// When cfg.charset is set, the collation is set by `SET NAMES <charset> COLLATE <collation>`.\n\t\t\treturn fmt.Errorf(\"unknown collation: %q\", cname)\n\t\t}\n\t}\n\n\t// Filler [23 bytes] (all 0x00)\n\t// or filler 19bytes + mariadb extCapabilities\n\tpos := 13\n\tif mc.capabilities&clientMySQL == 0 {\n\t\tfor ; pos < 13+19; pos++ {\n\t\t\tdata[pos] = 0\n\t\t}\n\t\t// MariaDB Extended Capabilities\n\t\tbinary.LittleEndian.PutUint32(data[13+19:], uint32(mc.extCapabilities))\n\t} else {\n\t\tfor ; pos < 13+23; pos++ {\n\t\t\tdata[pos] = 0\n\t\t}\n\t}\n","sourceCodeStart":330,"sourceCodeEnd":366,"githubUrl":"https://github.com/go-sql-driver/mysql/blob/c426bd93799de0f0e094c8f0582872c529d0ed0a/packets.go#L330-L366","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the exact collation name from the driver's supported set (run SHOW COLLATION and pick one with Id < 256).","Remove the collation parameter and rely on charset alone if a specific collation is not required.","Correct any spelling/casing mistake in the collation name."],"exampleFix":"// before — misspelled collation\nsql.Open(\"mysql\", \"user:pass@/db?charset=utf8mb4&collation=utf8mb4_unicde_ci\")\n\n// after\nsql.Open(\"mysql\", \"user:pass@/db?charset=utf8mb4&collation=utf8mb4_unicode_ci\")","handlingStrategy":"validation","validationCode":"// The collations map is unexported, so keep a vetted set of supported names\n// (those with Id < 256 from SHOW COLLATION) and validate membership:\nvar supportedCollation = map[string]bool{\n    \"utf8mb4_general_ci\": true, \"utf8mb4_unicode_ci\": true, \"latin1_swedish_ci\": true,\n}\nif cfgCollation != \"\" && !supportedCollation[cfgCollation] {\n    return fmt.Errorf(\"collation %q is not in the driver's built-in map\", cfgCollation)\n}","typeGuard":null,"tryCatchPattern":"if err := db.Ping(); err != nil {\n    if strings.Contains(err.Error(), \"unknown collation\") {\n        // correct or drop the collation parameter in the DSN\n    }\n}","preventionTips":["Copy collation names exactly from SHOW COLLATION (Id < 256).","Prefer a charset-only DSN when a specific collation is not required.","Watch for typos and casing differences in collation names."],"tags":["configuration","dsn","collation","charset","connection"],"analyzedSha":"c426bd93799de0f0e094c8f0582872c529d0ed0a","analyzedAt":"2026-08-04T21:52:59.219Z","schemaVersion":2}