{"id":"86ad687b96bab6d8","repo":"sidorares/node-mysql2","slug":"handshakeresponse-authtoken-must-be-a-buffer-when","errorCode":null,"errorMessage":"HandshakeResponse authToken must be a Buffer when provided","messagePattern":"HandshakeResponse authToken must be a Buffer when provided","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"lib/packets/handshake_response.js","lineNumber":29,"sourceCode":"    this.user = handshake.user || '';\n    this.database = handshake.database || '';\n    this.password = handshake.password || '';\n    this.passwordSha1 = handshake.passwordSha1;\n    this.authPluginData1 = handshake.authPluginData1;\n    this.authPluginData2 = handshake.authPluginData2;\n    this.compress = handshake.compress;\n    this.clientFlags = handshake.flags;\n    this.mariadbExtendedClientFlags = handshake.mariadbExtendedClientFlags || 0;\n\n    // Accept pre-calculated authToken and authPluginName from caller\n    // This allows the caller to optimize by using the server's preferred auth method\n    if (\n      handshake.authToken !== undefined &&\n      handshake.authPluginName !== undefined\n    ) {\n      // Validate types to fail fast with clear errors\n      if (!Buffer.isBuffer(handshake.authToken)) {\n        throw new TypeError(\n          'HandshakeResponse authToken must be a Buffer when provided'\n        );\n      }\n      if (typeof handshake.authPluginName !== 'string') {\n        throw new TypeError(\n          'HandshakeResponse authPluginName must be a string when provided'\n        );\n      }\n      this.authToken = handshake.authToken;\n      this.authPluginName = handshake.authPluginName;\n    } else {\n      // Fallback to legacy behavior: calculate mysql_native_password token\n      // TODO: pre-4.1 auth support\n      let authToken;\n      if (this.passwordSha1) {\n        authToken = auth41.calculateTokenFromPasswordSha(\n          this.passwordSha1,\n          this.authPluginData1,","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/sidorares/node-mysql2/blob/5ebe8903d6aea2d8ea1490e11b52491526e50f19/lib/packets/handshake_response.js#L11-L47","documentation":"HandshakeResponse accepts an optional pre-calculated `authToken` plus `authPluginName` (both must be provided together to take the optimised path). If both keys are present but `authToken` is not a Buffer, it throws at construction. This is an internal/advanced API used to short-circuit the initial handshake token; normal callers never set these fields.","triggerScenarios":"Constructing a HandshakeResponse packet directly (or via a custom auth flow) and passing `authToken` as a string or number while also passing `authPluginName`. Application code using the standard connection API will not hit this because the library computes the token itself.","commonSituations":"Advanced users building a custom handshake or mocking the packet in tests; a fork/patch that passes a string token by mistake.","solutions":["Pass authToken as a Buffer: `new HandshakeResponse({ ..., authToken: Buffer.from(token), authPluginName })`.","If you do not need the optimised path, omit both authToken and authPluginName and let HandshakeResponse compute the token."],"exampleFix":"// before\nnew HandshakeResponse({ ..., authToken: 'raw', authPluginName: 'x' });\n\n// after\nnew HandshakeResponse({ ..., authToken: Buffer.from('raw'), authPluginName: 'x' });","handlingStrategy":"type-guard","validationCode":"function buildHandshakeOpts(opts) {\n  if (opts.authToken !== undefined) {\n    if (!Buffer.isBuffer(opts.authToken)) throw new TypeError('authToken must be a Buffer');\n    if (typeof opts.authPluginName !== 'string') throw new TypeError('authPluginName must be a string');\n  }\n  return opts;\n}","typeGuard":"function isValidAuthToken(token) {\n  return token == null || Buffer.isBuffer(token);\n}","tryCatchPattern":null,"preventionTips":["Only set authToken/authPluginName if you compute them yourself; otherwise omit both.","Always wrap tokens with Buffer.from(...) before passing.","Keep HandshakeResponse construction in internal/test code only."],"tags":["auth","handshake","internal","buffer"],"analyzedSha":"5ebe8903d6aea2d8ea1490e11b52491526e50f19","analyzedAt":"2026-08-03T18:58:53.602Z","schemaVersion":2}