{"id":"7926a8c304754bdc","repo":"sidorares/node-mysql2","slug":"unknown-charset-charset","errorCode":null,"errorMessage":"Unknown charset '${charset}'","messagePattern":"Unknown charset '(.+?)'","errorType":"exception","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/5ebe8903d6aea2d8ea1490e11b52491526e50f19/lib/connection_config.js#L241-L277","documentation":"ConnectionConfig.getCharsetNumber() looks up the provided charset name (uppercased) in the built-in Charsets map; if it is not found the name is unknown to mysql2 and the connection cannot be created with a valid charset number. The charset must match one of the names defined in lib/constants/charsets.js.","triggerScenarios":"Setting `charset: 'utf8mb5'` (typo), `charset: 'utf-8'` (hyphenated, wrong — should be `UTF8MB4` or `utf8mb4`), or any name not present in the MySQL charset list that mysql2 ships. Case is folded to upper, but spelling must be exact.","commonSituations":"Typing `utf-8` or `utf8mb4_unicode_520_ci` style names that are not exact; copy-pasting an IANA charset name instead of a MySQL charset name; a server charset that mysql2's bundled constants do not yet list (rare, version lag).","solutions":["Use an exact MySQL charset name from the supported list, e.g. `charset: 'UTF8MB4'` or `charset: 'UTF8MB4_UNICODE_CI'`.","Check lib/constants/charsets.js for the exact spellings mysql2 recognises.","If you only need the collation number, use `charsetNumber` instead of `charset`."],"exampleFix":"// before\nmysql.createConnection({ host, user, password, charset: 'utf-8' });\n\n// after\nmysql.createConnection({ host, user, password, charset: 'UTF8MB4' });","handlingStrategy":"validation","validationCode":"const validCharsets = new Set(require('mysql2/lib/constants/charsets.js').map ? [] : Object.keys(require('mysql2/lib/constants/charsets.js')));\nfunction assertCharset(name) {\n  if (name && !(name.toUpperCase() in require('mysql2/lib/constants/charsets.js'))) {\n    throw new TypeError(`Charset '${name}' is not recognised by mysql2`);\n  }\n}","typeGuard":"function isKnownCharset(name, Charsets) {\n  return name == null || Object.prototype.hasOwnProperty.call(Charsets, name.toUpperCase());\n}","tryCatchPattern":null,"preventionTips":["Use the exact MySQL charset name (e.g. 'UTF8MB4').","Avoid IANA-style hyphenated names like 'utf-8'.","If unsure, omit `charset` and rely on the default (UTF8MB4_UNICODE_CI)."],"tags":["charset","connection-config"],"analyzedSha":"5ebe8903d6aea2d8ea1490e11b52491526e50f19","analyzedAt":"2026-08-03T18:58:53.602Z","schemaVersion":2}