{"record":{"id":"5a1eeb093f662952","repo":"nodejs/node","slug":"und-err-socks5-auth-failed","errorCode":"UND_ERR_SOCKS5_AUTH_FAILED","errorMessage":"Authentication failed","messagePattern":"Authentication failed","errorType":"exception","errorClass":"Socks5ProxyError","httpStatus":null,"severity":"error","filePath":"deps/undici/src/lib/core/socks5-client.js","lineNumber":262,"sourceCode":"  }\n\n  /**\n   * Handle authentication response\n   */\n  handleAuthResponse () {\n    if (this.buffer.length < 2) {\n      return // Not enough data yet\n    }\n\n    const version = this.buffer[0]\n    const status = this.buffer[1]\n\n    if (version !== 0x01) {\n      throw new Socks5ProxyError(`Invalid auth sub-negotiation version: ${version}`, 'UND_ERR_SOCKS5_AUTH_VERSION')\n    }\n\n    if (status !== 0x00) {\n      throw new Socks5ProxyError('Authentication failed', 'UND_ERR_SOCKS5_AUTH_FAILED')\n    }\n\n    this.buffer = this.buffer.subarray(2)\n    debug('authentication successful')\n    this.markAuthenticated()\n  }\n\n  /**\n   * Send CONNECT command\n   * @param {string} address - Target address (IP or domain)\n   * @param {number} port - Target port\n   */\n  connect (address, port) {\n    if (this.state === STATES.CONNECTING || this.state === STATES.CONNECTED) {\n      throw new InvalidArgumentError('Connection already in progress')\n    }\n\n    if (this.state !== STATES.AUTHENTICATED) {","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/deps/undici/src/lib/core/socks5-client.js#L244-L280","documentation":"Thrown in handleAuthResponse() when the STATUS byte of the auth reply is non-zero. Per RFC 1929, STATUS=0x00 means success; any other value means authentication failed (bad credentials). This is the proxy actively rejecting the username/password.","triggerScenarios":"Wrong username or password; expired or rotated credentials; credentials for a different realm/account; trailing whitespace or encoding issues in the credential strings.","commonSituations":"Typo in env var values; copy-paste introduced a newline; secrets rotated server-side but not in the client; URL-encoded credentials not decoded from the proxy URL.","solutions":["Verify the username and password against the proxy's configured credentials.","Trim whitespace and check for accidental newlines in credential strings.","If credentials come from a URL, ensure percent-encoding is decoded correctly.","Re-test with curl --socks5-hostname user:pass@host to isolate the client from the credentials."],"exampleFix":"// before\nusername: process.env.PROXY_USER,\npassword: 'pass\\n'  // trailing newline\n\n// after\nusername: process.env.PROXY_USER?.trim(),\npassword: process.env.PROXY_PASS?.trim()","handlingStrategy":"retry","validationCode":"function cleanCred(v) {\n  if (typeof v !== 'string') throw new Error('credential missing')\n  const trimmed = v.trim()\n  if (trimmed.length === 0) throw new Error('credential empty')\n  return trimmed\n}","typeGuard":null,"tryCatchPattern":"try { client.handshake() } catch (e) {\n  if (e.code === 'UND_ERR_SOCKS5_AUTH_FAILED') { /* verify/refresh credentials, then retry on a new client */ }\n  else throw e\n}","preventionTips":["Trim and validate credentials before passing them in.","Decode percent-encoded credentials from proxy URLs.","Coordinate credential rotation between client and proxy."],"tags":["socks5","proxy","authentication","credentials","network"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}