sidorares/node-mysql2 · error · TypeError

Unknown charset '${charset}'

Error message

Unknown charset '${charset}'

What it means

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.

Source

Thrown at lib/connection_config.js:259

      'MULTI_RESULTS',
      'TRANSACTIONS',
      'SESSION_TRACK',
      'CONNECT_ATTRS',
      'CLIENT_QUERY_ATTRIBUTES',
    ];
    if (options && options.multipleStatements) {
      defaultFlags.push('MULTI_STATEMENTS');
    }
    defaultFlags.push('PLUGIN_AUTH');
    defaultFlags.push('PLUGIN_AUTH_LENENC_CLIENT_DATA');

    return defaultFlags;
  }

  static getCharsetNumber(charset) {
    const num = Charsets[charset.toUpperCase()];
    if (num === undefined) {
      throw new TypeError(`Unknown charset '${charset}'`);
    }
    return num;
  }

  static getSSLProfile(name) {
    if (!SSLProfiles) {
      SSLProfiles = require('./constants/ssl_profiles.js');
    }
    const ssl = SSLProfiles[name];
    if (ssl === undefined) {
      throw new TypeError(`Unknown SSL profile '${name}'`);
    }
    return ssl;
  }

  static parseUrl(url) {
    const parsedUrl = new URL(url);
    const options = {

View on GitHub (pinned to 5ebe8903d6)

Solutions

1. Use an exact MySQL charset name from the supported list, e.g. `charset: 'UTF8MB4'` or `charset: 'UTF8MB4_UNICODE_CI'`.
2. Check lib/constants/charsets.js for the exact spellings mysql2 recognises.
3. If you only need the collation number, use `charsetNumber` instead of `charset`.

Example fix

// before
mysql.createConnection({ host, user, password, charset: 'utf-8' });

// after
mysql.createConnection({ host, user, password, charset: 'UTF8MB4' });

const validCharsets = new Set(require('mysql2/lib/constants/charsets.js').map ? [] : Object.keys(require('mysql2/lib/constants/charsets.js')));
function assertCharset(name) {
  if (name && !(name.toUpperCase() in require('mysql2/lib/constants/charsets.js'))) {
    throw new TypeError(`Charset '${name}' is not recognised by mysql2`);
  }
}

function isKnownCharset(name, Charsets) {
  return name == null || Object.prototype.hasOwnProperty.call(Charsets, name.toUpperCase());
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• SSL profile must be an object, instead it's a ${typeof this.
• Unknown SSL profile '${name}'
• "user" connection config property must be a string
• "database" connection config property must be a string

AI-assisted analysis of sidorares/node-mysql2@5ebe8903d6 (2026-08-03). Data as JSON: /data/errors/7926a8c304754bdc.json. Report an issue: GitHub.