{"record":{"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/03d76c7e07908e255ce62d126d07ede3f2365d86/packets.go#L330-L366","documentation":"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.)","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a valid collation name from the driver's table, e.g. utf8mb4_general_ci or utf8mb4_0900_ai_ci.","Remove the collation parameter to let the charset pick its default collation.","Cross-check the exact spelling/case against the server's 'SHOW COLLATION' output."],"exampleFix":"// before\nsql.Open(\"mysql\", \"user@tcp(127.0.0.1:3306)/db?charset=utf8mb4&collation=utf8mb4_general\")\n// after\nsql.Open(\"mysql\", \"user@tcp(127.0.0.1:3306)/db?charset=utf8mb4&collation=utf8mb4_general_ci\")","handlingStrategy":"validation","validationCode":"// Validate the collation name against the driver's known set (mirror collations.go).\nif _, ok := knownCollations[collation]; !ok {\n    return fmt.Errorf(\"unknown collation: %s\", collation)\n}","typeGuard":"null","tryCatchPattern":"// Unknown-collation errors surface at handshake (first query/Ping).\nif err := db.Ping(); err != nil {\n    if strings.Contains(err.Error(), \"unknown collation\") {\n        // fix the DSN collation and reconnect\n    }\n}","preventionTips":["Copy collation names verbatim from 'SHOW COLLATION'.","Drop the collation param if you only need the charset default.","Keep the driver version current so newer collations are recognized."],"tags":["go","mysql","collation","charset","config"],"backgroundTag":null,"analyzedSha":"03d76c7e07908e255ce62d126d07ede3f2365d86","analyzedAt":"2026-08-07T10:39:17.340Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}