{"record":{"id":"30300be63fd2392f","repo":"MyCATApache/Mycat-Server","slug":"unknown-charsetindex","errorCode":null,"errorMessage":"Unknown charsetIndex:","messagePattern":"Unknown charsetIndex:","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/main/java/io/mycat/backend/mysql/nio/MySQLConnectionAuthenticator.java","lineNumber":133,"sourceCode":"\t\t\t}\n\t\t\tthrow e;\n\t\t}\n\t}\n\n\tprivate void processHandShakePacket(byte[] data) {\n\t\t// 设置握手数据包\n\t\tHandshakePacket packet= new HandshakePacket();\n\t\tpacket.read(data);\n\t\tsource.setHandshake(packet);\n\t\tsource.setThreadId(packet.threadId);\n\n\t\t// 设置字符集编码\n\t\tint charsetIndex = (packet.serverCharsetIndex & 0xff);\n\t\tString charset = CharsetUtil.getCharset(charsetIndex);\n\t\tif (charset != null) {\n\t\t\tsource.setCharset(charset);\n\t\t} else {\n\t\t\tthrow new RuntimeException(\"Unknown charsetIndex:\" + charsetIndex);\n\t\t}\n\t}\n\n\tprivate void auth323(byte packetId) {\n\t\t// 发送323响应认证数据包\n\t\tReply323Packet r323 = new Reply323Packet();\n\t\tr323.packetId = ++packetId;\n\t\tString pass = source.getPassword();\n\t\tif (pass != null && pass.length() > 0) {\n\t\t\tbyte[] seed = source.getHandshake().seed;\n\t\t\tr323.seed = SecurityUtil.scramble323(pass, new String(seed))\n\t\t\t\t\t.getBytes();\n\t\t}\n\t\tr323.write(source);\n\t}\n\n}","sourceCodeStart":115,"sourceCodeEnd":150,"githubUrl":"https://github.com/MyCATApache/Mycat-Server/blob/65f8d8beb752f935752f2a0eec0ab017facab9ef/src/main/java/io/mycat/backend/mysql/nio/MySQLConnectionAuthenticator.java#L115-L150","documentation":"During the MySQL handshake, MySQLConnectionAuthenticator.processHandShakePacket reads the server's charset index from the handshake packet and maps it to a charset name via CharsetUtil.getCharset(). If the returned charset is null — the index is not present in MyCat's charset table — it throws this RuntimeException, aborting backend connection authentication.","triggerScenarios":"The MySQL server sends a handshake packet whose serverCharsetIndex (serverCharsetIndex & 0xff) is not in MyCat's CharsetUtil mapping — typically a newer or unusual collation id, or a charset index for a charset MyCat does not know.","commonSituations":"Connecting to a newer MySQL (5.7/8.0) or MariaDB whose default collation id is absent from the old MyCat charset table; servers configured with uncommon default charsets like utf8mb4_0900_ai_ci (id 255) or gb18030; connecting through a proxy that alters the handshake.","solutions":["Map the unknown charset index explicitly: add an entry to CharsetUtil's charset index table (or MyCat's charset config) for the reported index before connecting","Configure the MySQL server (or the user account) to use a charset MyCat knows, e.g. SET GLOBAL character_set_server=utf8 or init_connect on the account","Upgrade MyCat to a version whose CharsetUtil includes the server's collation ids","Patch the code to fall back to a default charset (e.g. utf8) instead of throwing when the index is unmapped"],"exampleFix":"// before\nif (charset != null) { source.setCharset(charset); } else { throw new RuntimeException(\"Unknown charsetIndex:\" + charsetIndex); }\n// after\nif (charset != null) { source.setCharset(charset); } else { LOGGER.warn(\"Unknown charsetIndex:\" + charsetIndex + \", fallback to utf8\"); source.setCharset(\"utf8\"); }","handlingStrategy":"validation","validationCode":"int idx = serverCharsetIndex & 0xff;\nif (CharsetUtil.getCharset(idx) == null) {\n    throw new IllegalStateException(\"Server charset index \" + idx + \" unsupported; use a server charset MyCat knows (e.g. utf8)\");\n}","typeGuard":null,"tryCatchPattern":"try { connect(...); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"Unknown charsetIndex:\")) { /* reconfigure server charset or fallback */ } else { throw e; } }","preventionTips":["Pin the MySQL server's default charset to one MyCat's CharsetUtil maps (utf8/latin1/gbk)","Check charset index support before upgrading the DB server version","Add all expected collation ids to CharsetUtil in tests"],"tags":["mysql","charset","handshake","encoding"],"backgroundTag":"invalid-enum-value","analyzedSha":"65f8d8beb752f935752f2a0eec0ab017facab9ef","analyzedAt":"2026-09-11T00:12:21.696Z","contentChangedAt":"2026-09-11T00:12:21.696Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}