{"record":{"id":"b7c68ec7885297f6","repo":"nodejs/node","slug":"und-err-socks5-version","errorCode":"UND_ERR_SOCKS5_VERSION","errorMessage":"Invalid SOCKS version: ${version}","messagePattern":"Invalid SOCKS version: (.+?)","errorType":"exception","errorClass":"Socks5ProxyError","httpStatus":null,"severity":"error","filePath":"deps/undici/src/lib/core/socks5-client.js","lineNumber":191,"sourceCode":"      request[2 + i] = method\n    })\n\n    this.socket.write(request)\n  }\n\n  /**\n   * Handle handshake response from server\n   */\n  handleHandshakeResponse () {\n    if (this.buffer.length < 2) {\n      return // Not enough data yet\n    }\n\n    const version = this.buffer[0]\n    const method = this.buffer[1]\n\n    if (version !== SOCKS_VERSION) {\n      throw new Socks5ProxyError(`Invalid SOCKS version: ${version}`, 'UND_ERR_SOCKS5_VERSION')\n    }\n\n    if (method === AUTH_METHODS.NO_ACCEPTABLE) {\n      throw new Socks5ProxyError('No acceptable authentication method', 'UND_ERR_SOCKS5_AUTH_REJECTED')\n    }\n\n    this.buffer = this.buffer.subarray(2)\n    debug('server selected auth method', method)\n\n    if (method === AUTH_METHODS.NO_AUTH) {\n      this.markAuthenticated()\n    } else if (method === AUTH_METHODS.USERNAME_PASSWORD) {\n      this.state = STATES.AUTHENTICATING\n      this.sendAuthRequest()\n    } else {\n      throw new Socks5ProxyError(`Unsupported authentication method: ${method}`, 'UND_ERR_SOCKS5_AUTH_METHOD')\n    }\n  }","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/deps/undici/src/lib/core/socks5-client.js#L173-L209","documentation":"Thrown in handleHandshakeResponse when the first byte of the server's method-selection reply is not SOCKS_VERSION (0x05 per RFC 1928). A correct SOCKS5 server replies with VER=0x05; any other value means the endpoint is not speaking SOCKS5, or is speaking a different SOCKS version, or is not a proxy at all.","triggerScenarios":"Pointing the client at an HTTP/HTTPS proxy port, a SOCKS4 proxy, or a plain TCP service; a man-in-the-middle returning an HTTP error page; a SOCKS5 server implementation that omits the version byte.","commonSituations":"Wrong proxy URL scheme (e.g. http:// instead of socks5://); port misconfiguration hitting a web server; SOCKS4-only proxy; corporate proxy that returns a 400 Bad Request in plaintext.","solutions":["Verify the proxy URL uses the socks5 (or socks5h) scheme and the correct host/port.","Confirm the endpoint is actually a SOCKS5 server (test with curl --socks5-hostname).","If the proxy is SOCKS4, switch to a SOCKS4 client or a SOCKS5-capable proxy.","Inspect the raw bytes received to confirm whether an HTTP response is being parsed as SOCKS."],"exampleFix":"// before\nconst proxy = 'http://proxy.corp:8080'  // wrong scheme\n\n// after\nconst proxy = 'socks5://proxy.corp:1080'","handlingStrategy":"try-catch","validationCode":"const PROXY_URL = new URL(opts.proxy)\nif (!/^socks5h?$/.test(PROXY_URL.protocol.replace(':',''))) {\n  throw new Error('proxy must use socks5 or socks5h scheme')\n}","typeGuard":null,"tryCatchPattern":"try { client.handshake() } catch (e) {\n  if (e.code === 'UND_ERR_SOCKS5_VERSION') {\n    // endpoint is not a SOCKS5 server; check proxy URL/port\n  } else throw e\n}","preventionTips":["Always validate the proxy URL scheme before connecting.","Smoke-test the proxy with curl --socks5-hostname during setup.","Distinguish SOCKS4 from SOCKS5 endpoints in your proxy catalog."],"tags":["socks5","proxy","protocol","network","config"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}