{"record":{"id":"7926a8c304754bdc","repo":"sidorares/node-mysql2","slug":"unknown-charset-charset","errorCode":null,"errorMessage":"Unknown charset '${charset}'","messagePattern":"Unknown charset '(.+?)'","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"lib/connection_config.js","lineNumber":259,"sourceCode":"      'MULTI_RESULTS',\n      'TRANSACTIONS',\n      'SESSION_TRACK',\n      'CONNECT_ATTRS',\n      'CLIENT_QUERY_ATTRIBUTES',\n    ];\n    if (options && options.multipleStatements) {\n      defaultFlags.push('MULTI_STATEMENTS');\n    }\n    defaultFlags.push('PLUGIN_AUTH');\n    defaultFlags.push('PLUGIN_AUTH_LENENC_CLIENT_DATA');\n\n    return defaultFlags;\n  }\n\n  static getCharsetNumber(charset) {\n    const num = Charsets[charset.toUpperCase()];\n    if (num === undefined) {\n      throw new TypeError(`Unknown charset '${charset}'`);\n    }\n    return num;\n  }\n\n  static getSSLProfile(name) {\n    if (!SSLProfiles) {\n      SSLProfiles = require('./constants/ssl_profiles.js');\n    }\n    const ssl = SSLProfiles[name];\n    if (ssl === undefined) {\n      throw new TypeError(`Unknown SSL profile '${name}'`);\n    }\n    return ssl;\n  }\n\n  static parseUrl(url) {\n    const parsedUrl = new URL(url);\n    const options = {","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/sidorares/node-mysql2/blob/8b1f829d3706404ab372cf97bd77ebcf86578d97/lib/connection_config.js#L241-L277","documentation":"ConnectionConfig.getCharsetNumber (lib/connection_config.js:256-262) uppercases the charset string and looks it up in the Charsets constant map; if not found it throws TypeError. The lookup must match MySQL's charset name (e.g. UTF8MB4_UNICODE_CI) exactly after uppercasing.","triggerScenarios":"Passing charset: 'utf-8' or 'utf8mb4_general_ci' with a typo; using an IANA charset name instead of a MySQL charset name; a charset removed or renamed in the server version.","commonSituations":"Copy from HTML/HTTP charset strings (utf-8) instead of MySQL names; case/underscore mismatch (utf8mb4-unicode-ci vs UTF8MB4_UNICODE_CI — underscore form is required); referring to a collation that exists on a newer server only.","solutions":["Use the exact MySQL charset/collation name, uppercase with underscores: charset: 'UTF8MB4_UNICODE_CI'.","Omit charset to accept the default UTF8MB4_UNICODE_CI (connection_config.js:176).","Confirm the name with SHOW COLLATION on the target server."],"exampleFix":"// before\ncreateConnection({ charset: 'utf-8' });\n\n// after\ncreateConnection({ charset: 'UTF8MB4_UNICODE_CI' });","handlingStrategy":"validation","validationCode":"const mysql = require('mysql2');\nconst { Charsets } = mysql; // or import constants\nfunction assertCharset(name) {\n  if (name && !Object.prototype.hasOwnProperty.call(require('mysql2/lib/constants/charsets'), name.toUpperCase())) {\n    throw new TypeError(`Unsupported MySQL charset: ${name}`);\n  }\n}","typeGuard":"const isKnownCharset = (name, charsets) => Object.prototype.hasOwnProperty.call(charsets, String(name).toUpperCase());","tryCatchPattern":null,"preventionTips":["Use SHOW COLLATION on the server to confirm the exact name.","Omit charset to accept the safe default UTF8MB4_UNICODE_CI."],"tags":["charset","connection-config","validation"],"backgroundTag":null,"analyzedSha":"8b1f829d3706404ab372cf97bd77ebcf86578d97","analyzedAt":"2026-08-11T02:54:28.964Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}