{"record":{"id":"a6ac27ba0c6320e3","repo":"nodejs/node","slug":"und-err-socks5-reply-reply","errorCode":"UND_ERR_SOCKS5_REPLY_${reply}","errorMessage":"SOCKS5 connection failed: ${errorMessage}","messagePattern":"SOCKS5 connection failed: (.+?)","errorType":"exception","errorClass":"Socks5ProxyError","httpStatus":null,"severity":"error","filePath":"deps/undici/src/lib/core/socks5-client.js","lineNumber":352,"sourceCode":"      responseLength += 4 + 2 // IPv4 + port\n    } else if (addressType === ADDRESS_TYPES.DOMAIN) {\n      if (this.buffer.length < 5) {\n        return // Need domain length byte\n      }\n      responseLength += 1 + this.buffer[4] + 2 // length byte + domain + port\n    } else if (addressType === ADDRESS_TYPES.IPV6) {\n      responseLength += 16 + 2 // IPv6 + port\n    } else {\n      throw new Socks5ProxyError(`Invalid address type in reply: ${addressType}`, 'UND_ERR_SOCKS5_ADDR_TYPE')\n    }\n\n    if (this.buffer.length < responseLength) {\n      return // Not enough data for full response\n    }\n\n    if (reply !== REPLY_CODES.SUCCEEDED) {\n      const errorMessage = this.getReplyErrorMessage(reply)\n      throw new Socks5ProxyError(`SOCKS5 connection failed: ${errorMessage}`, `UND_ERR_SOCKS5_REPLY_${reply}`)\n    }\n\n    // Parse bound address and port\n    let boundAddress\n    let offset = 4\n\n    if (addressType === ADDRESS_TYPES.IPV4) {\n      boundAddress = Array.from(this.buffer.subarray(offset, offset + 4)).join('.')\n      offset += 4\n    } else if (addressType === ADDRESS_TYPES.DOMAIN) {\n      const domainLength = this.buffer[offset]\n      offset += 1\n      boundAddress = this.buffer.subarray(offset, offset + domainLength).toString()\n      offset += domainLength\n    } else if (addressType === ADDRESS_TYPES.IPV6) {\n      // Parse IPv6 address from 16-byte buffer\n      const parts = []\n      for (let i = 0; i < 8; i++) {","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/deps/undici/src/lib/core/socks5-client.js#L334-L370","documentation":"Thrown in handleConnectResponse() when the REP (reply code) is not REPLY_CODES.SUCCEEDED (0x00). The proxy itself received the CONNECT but could not establish the target connection (e.g. host unreachable, connection refused, TTL expired, command not supported). The dynamic error code is UND_ERR_SOCKS5_REPLY_<rep>.","triggerScenarios":"Target host:port unreachable from the proxy; target refused the connection; DNS resolution failure at the proxy (with socks5 vs socks5h); proxy policy forbidding the destination; network ACL between proxy and target.","commonSituations":"Wrong target host/port; target service down; using socks5:// (proxy does local DNS) for a host the proxy cannot resolve, vs socks5h:// (remote DNS); firewall rules between proxy and target.","solutions":["Inspect getReplyErrorMessage(rep) to map the code to a cause (e.g. 0x04=host unreachable, 0x05=connection refused).","Verify the target host resolves and is reachable from the proxy's network, not just yours.","Use socks5h:// to force remote DNS resolution by the proxy.","Retry with backoff for transient codes; fix the target address for permanent ones."],"exampleFix":"// before\nproxy: 'socks5://proxy:1080'  // proxy can't resolve target locally\n\n// after\nproxy: 'socks5h://proxy:1080'  // proxy resolves target DNS remotely","handlingStrategy":"retry","validationCode":"function isRetryableReply(rep) {\n  // 0x03 network unreachable, 0x04 host unreachable, 0x05 connection refused, 0x06 TTL expired\n  return [0x03, 0x04, 0x05, 0x06].includes(rep)\n}","typeGuard":null,"tryCatchPattern":"try { client.connect(host, port) } catch (e) {\n  if (/^UND_ERR_SOCKS5_REPLY_/.test(e.code)) {\n    const rep = Number(e.code.slice('UND_ERR_SOCKS5_REPLY_'.length))\n    if (isRetryableReply(rep)) { /* backoff + retry on new client */ }\n    else throw e // permanent (e.g. 0x02 not allowed, 0x07 command not supported)\n  } else throw e\n}","preventionTips":["Use socks5h:// so the proxy does remote DNS.","Verify the target is reachable from the proxy's network.","Map the REP code to decide retry vs fail-fast."],"tags":["socks5","proxy","network","connectivity","config"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}