nodejs/node · error · Socks5ProxyError

UND_ERR_SOCKS5_VERSION

UND_ERR_SOCKS5_VERSION

Error message

Invalid SOCKS version: ${version}

What it means

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.

Source

Thrown at deps/undici/src/lib/core/socks5-client.js:191

      request[2 + i] = method
    })

    this.socket.write(request)
  }

  /**
   * Handle handshake response from server
   */
  handleHandshakeResponse () {
    if (this.buffer.length < 2) {
      return // Not enough data yet
    }

    const version = this.buffer[0]
    const method = this.buffer[1]

    if (version !== SOCKS_VERSION) {
      throw new Socks5ProxyError(`Invalid SOCKS version: ${version}`, 'UND_ERR_SOCKS5_VERSION')
    }

    if (method === AUTH_METHODS.NO_ACCEPTABLE) {
      throw new Socks5ProxyError('No acceptable authentication method', 'UND_ERR_SOCKS5_AUTH_REJECTED')
    }

    this.buffer = this.buffer.subarray(2)
    debug('server selected auth method', method)

    if (method === AUTH_METHODS.NO_AUTH) {
      this.markAuthenticated()
    } else if (method === AUTH_METHODS.USERNAME_PASSWORD) {
      this.state = STATES.AUTHENTICATING
      this.sendAuthRequest()
    } else {
      throw new Socks5ProxyError(`Unsupported authentication method: ${method}`, 'UND_ERR_SOCKS5_AUTH_METHOD')
    }
  }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Verify the proxy URL uses the socks5 (or socks5h) scheme and the correct host/port.
2. Confirm the endpoint is actually a SOCKS5 server (test with curl --socks5-hostname).
3. If the proxy is SOCKS4, switch to a SOCKS4 client or a SOCKS5-capable proxy.
4. Inspect the raw bytes received to confirm whether an HTTP response is being parsed as SOCKS.

Example fix

// before
const proxy = 'http://proxy.corp:8080'  // wrong scheme

// after
const proxy = 'socks5://proxy.corp:1080'

const PROXY_URL = new URL(opts.proxy)
if (!/^socks5h?$/.test(PROXY_URL.protocol.replace(':',''))) {
  throw new Error('proxy must use socks5 or socks5h scheme')
}

try { client.handshake() } catch (e) {
  if (e.code === 'UND_ERR_SOCKS5_VERSION') {
    // endpoint is not a SOCKS5 server; check proxy URL/port
  } else throw e
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• UND_ERR_SOCKS5_AUTH_REJECTED
• UND_ERR_SOCKS5_REPLY_VERSION
• UND_ERR_SOCKS5_ADDR_TYPE
• UND_ERR_SOCKS5_REPLY_${reply}
• UND_ERR_SOCKET

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/b7c68ec7885297f6. Report an issue: GitHub.