{"record":{"id":"46a11e07818edcef","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 (.+?) on how to configure or author authentication plugins\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","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/8b1f829d3706404ab372cf97bd77ebcf86578d97/lib/commands/auth_switch.js#L81-L117","documentation":"In authSwitchRequest (lib/commands/auth_switch.js:97-102), the server's AuthSwitchRequest names a plugin that is neither one of the four built-ins (caching_sha2_password, sha256_password, mysql_native_password, mysql_clear_password) nor present in connection.config.authPlugins. The driver cannot proceed without an implementation of that plugin, so it throws fatal. The message still references a TODO doc URL that has not been filled in.","triggerScenarios":"MySQL server account pinned to an auth plugin the client does not ship (e.g. ed25519 on MariaDB, or an enterprise PAM/LDAP plugin); a MariaDB server defaulting to a plugin not in the standard set; connecting to an AWS Aurora or ProxySQL instance that advertises a custom plugin name.","commonSituations":"MariaDB with unix_socket or ed25519; a hardened server using auth_pam; newer server advertising a plugin the older mysql2 client predates.","solutions":["Provide a custom plugin implementation via createConnection({ authPlugins: { '<pluginName>': pluginFactory } }).","Change the server account to a supported plugin: ALTER USER ... IDENTIFIED WITH 'mysql_native_password' (or caching_sha2_password) BY 'pw'.","Upgrade mysql2 — newer releases add built-in support for more plugins.","For MariaDB ed25519, install/use a compatible client or implement the authPlugins callback."],"exampleFix":"// before\nconst conn = mysql.createConnection({ host, user, password });\n\n// after: supply the missing plugin factory\nconst conn = mysql.createConnection({\n  host, user, password,\n  authPlugins: { ed25519: ed25519PluginFactory },\n});","handlingStrategy":"validation","validationCode":"const knownPlugins = ['caching_sha2_password','sha256_password','mysql_native_password','mysql_clear_password'];\nif (!knownPlugins.includes(serverPlugin) && !(config.authPlugins || {})[serverPlugin]) {\n  throw new Error(`Provide authPlugins.${serverPlugin} or ALTER USER to a supported plugin.`);\n}","typeGuard":"const isKnownPlugin = (name, authPlugins = {}) =>\n  ['caching_sha2_password','sha256_password','mysql_native_password','mysql_clear_password'].includes(name) || Object.prototype.hasOwnProperty.call(authPlugins, name);","tryCatchPattern":"try { await mysql.createConnection(cfg); } catch (e) { if (/unknown plugin/.test(e.message)) { /* add authPlugins entry or ALTER USER */ } throw e; }","preventionTips":["Pre-create authPlugins entries for every plugin the fleet uses.","Pin server accounts to a client-supported plugin via ALTER USER."],"tags":["authentication","auth-plugin","server-config","connection"],"backgroundTag":null,"analyzedSha":"8b1f829d3706404ab372cf97bd77ebcf86578d97","analyzedAt":"2026-08-11T02:54:28.964Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}