{"id":"71c8964c280e7650","repo":"sidorares/node-mysql2","slug":"server-requests-authentication-using-unknown-plugi","errorCode":null,"errorMessage":"Server requests authentication using unknown plugin ${pluginName}. See TODO: add plugins doco here on how to configure or author authentication plugins.","messagePattern":"Server requests authentication using unknown plugin (.+?)\\. See TODO: add plugins doco here on how to configure or author authentication plugins\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/commands/auth_switch.js","lineNumber":99,"sourceCode":"      );\n    if (!hasCustomPlugin && !connection.config.enableCleartextPlugin) {\n      const err = new Error(\n        'Server requested authentication using mysql_clear_password, ' +\n          'which sends the password in plaintext over the network and is ' +\n          'disabled by default. To enable it, set the `enableCleartextPlugin` ' +\n          'option to `true` in your connection configuration, or provide a ' +\n          'custom `mysql_clear_password` auth plugin via the `authPlugins` ' +\n          'option. Only use this over a secure connection (TLS/SSL).'\n      );\n      err.code = 'MYSQL_CLEAR_PASSWORD_NOT_ENABLED';\n      err.fatal = true;\n      throw err;\n    }\n  }\n\n  const authPlugin = getAuthPlugin(pluginName, connection);\n  if (!authPlugin) {\n    throw new Error(\n      `Server requests authentication using unknown plugin ${pluginName}. See ${'TODO: add plugins doco here'} on how to configure or author authentication plugins.`\n    );\n  }\n  connection._authPlugin = authPlugin({ connection, command });\n  Promise.resolve(connection._authPlugin(pluginData))\n    .then((data) => {\n      if (data) {\n        connection.writePacket(new Packets.AuthSwitchResponse(data).toPacket());\n      }\n    })\n    .catch((err) => {\n      authSwitchPluginError(err, command);\n    });\n}\n\nfunction authSwitchRequestMoreData(packet, connection, command) {\n  const { data } = Packets.AuthSwitchRequestMoreData.fromPacket(packet);\n","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/sidorares/node-mysql2/blob/5ebe8903d6aea2d8ea1490e11b52491526e50f19/lib/commands/auth_switch.js#L81-L117","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register the missing plugin via the `authPlugins` config option, providing a factory that implements the plugin's auth exchange.","For ed25519 on MariaDB, install and register a compatible ed25519 auth plugin implementation in `authPlugins`.","Change the MySQL/MariaDB user's auth plugin to one mysql2 supports natively (e.g. mysql_native_password).","Upgrade mysql2 — newer versions bundle more plugin support."],"exampleFix":"// before\nconst conn = mysql.createConnection({ host, user, password });\n// server requests 'ed25519' → unknown plugin error\n\n// after — register a custom plugin\nconst conn = mysql.createConnection({\n  host,\n  user,\n  password,\n  authPlugins: {\n    ed25519: require('mysql2-ed25519-plugin')(),\n  },\n});","handlingStrategy":"validation","validationCode":"const knownPlugins = new Set(['mysql_native_password','caching_sha2_password','sha256_password','mysql_clear_password']);\nfunction ensurePluginSupported(pluginName, authPlugins) {\n  if (!knownPlugins.has(pluginName) && !(authPlugins && Object.prototype.hasOwnProperty.call(authPlugins, pluginName))) {\n    throw new Error(`Auth plugin '${pluginName}' is not registered. Add it to authPlugins config.`);\n  }\n}","typeGuard":"function isAuthPluginRegistered(pluginName, authPlugins, builtins) {\n  return Boolean(builtins[pluginName] || (authPlugins && Object.prototype.hasOwnProperty.call(authPlugins, pluginName)));\n}","tryCatchPattern":null,"preventionTips":["Register any non-standard server plugin in authPlugins before connecting.","Check the MySQL user's plugin column (`SELECT user, plugin FROM mysql.user`) when planning a connection.","For MariaDB ed25519, install a compatible plugin module."],"tags":["auth","auth-plugin","connection","mariadb"],"analyzedSha":"5ebe8903d6aea2d8ea1490e11b52491526e50f19","analyzedAt":"2026-08-03T18:58:53.602Z","schemaVersion":2}