sidorares/node-mysql2 · error · Error

Server requests authentication using unknown plugin ${plugin

Error message

Server requests authentication using unknown plugin ${pluginName}. See TODO: add plugins doco here on how to configure or author authentication plugins.

What it means

During the auth-switch phase the server requested a plugin whose name is neither one of mysql2's built-ins (mysql_native_password, caching_sha2_password, sha256_password, mysql_clear_password) nor registered in `connection.config.authPlugins`. mysql2 therefore has no code to run for that auth method and refuses to proceed. The TODO doco link in the message is a known placeholder.

Source

Thrown at lib/commands/auth_switch.js:99

      );
    if (!hasCustomPlugin && !connection.config.enableCleartextPlugin) {
      const err = new Error(
        'Server requested authentication using mysql_clear_password, ' +
          'which sends the password in plaintext over the network and is ' +
          'disabled by default. To enable it, set the `enableCleartextPlugin` ' +
          'option to `true` in your connection configuration, or provide a ' +
          'custom `mysql_clear_password` auth plugin via the `authPlugins` ' +
          'option. Only use this over a secure connection (TLS/SSL).'
      );
      err.code = 'MYSQL_CLEAR_PASSWORD_NOT_ENABLED';
      err.fatal = true;
      throw err;
    }
  }

  const authPlugin = getAuthPlugin(pluginName, connection);
  if (!authPlugin) {
    throw new Error(
      `Server requests authentication using unknown plugin ${pluginName}. See ${'TODO: add plugins doco here'} on how to configure or author authentication plugins.`
    );
  }
  connection._authPlugin = authPlugin({ connection, command });
  Promise.resolve(connection._authPlugin(pluginData))
    .then((data) => {
      if (data) {
        connection.writePacket(new Packets.AuthSwitchResponse(data).toPacket());
      }
    })
    .catch((err) => {
      authSwitchPluginError(err, command);
    });
}

function authSwitchRequestMoreData(packet, connection, command) {
  const { data } = Packets.AuthSwitchRequestMoreData.fromPacket(packet);

View on GitHub (pinned to 5ebe8903d6)

Solutions

1. Register the missing plugin via the `authPlugins` config option, providing a factory that implements the plugin's auth exchange.
2. For ed25519 on MariaDB, install and register a compatible ed25519 auth plugin implementation in `authPlugins`.
3. Change the MySQL/MariaDB user's auth plugin to one mysql2 supports natively (e.g. mysql_native_password).
4. Upgrade mysql2 — newer versions bundle more plugin support.

Example fix

// before
const conn = mysql.createConnection({ host, user, password });
// server requests 'ed25519' → unknown plugin error

// after — register a custom plugin
const conn = mysql.createConnection({
  host,
  user,
  password,
  authPlugins: {
    ed25519: require('mysql2-ed25519-plugin')(),
  },
});

const knownPlugins = new Set(['mysql_native_password','caching_sha2_password','sha256_password','mysql_clear_password']);
function ensurePluginSupported(pluginName, authPlugins) {
  if (!knownPlugins.has(pluginName) && !(authPlugins && Object.prototype.hasOwnProperty.call(authPlugins, pluginName))) {
    throw new Error(`Auth plugin '${pluginName}' is not registered. Add it to authPlugins config.`);
  }
}

function isAuthPluginRegistered(pluginName, authPlugins, builtins) {
  return Boolean(builtins[pluginName] || (authPlugins && Object.prototype.hasOwnProperty.call(authPlugins, pluginName)));
}

When it happens

Trigger: Connecting to a server whose user account uses an auth plugin mysql2 does not bundle — e.g. MariaDB's `ed25519`, `auth_pam`, `auth_socket`, `dialog`, or a custom plugin. Also seen when an older mysql2 version connects to a newer server, or vice-versa.

Common situations: MariaDB accounts using ed25519 (common with recent MariaDB); PAM-authenticated accounts; socket-peer-cred accounts; a version mismatch where the plugin name string changed; connecting to an AWS/Aurora endpoint that presents a non-standard plugin.

Related errors

• Invalid AuthMoreData packet received by caching_sha2_passwor
• Unexpected data in AuthMoreData packet received by caching_s
• Unexpected data in AuthMoreData packet received by sha256_pa
• AuthPluginMoreData received but no auth plugin instance foun
• Unexpected data in AuthMoreData packet received by caching_s

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