nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

socket is required

What it means

Thrown by the Socks5Client constructor when the first argument (socket) is falsy. The class wraps an existing socket to drive the SOCKS5 protocol, so without one there is nothing to read/write. This is a programmer-facing guard, not a network condition.

Source

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

  HANDSHAKING: 'handshaking',
  AUTHENTICATING: 'authenticating',
  AUTHENTICATED: 'authenticated',
  CONNECTING: 'connecting',
  CONNECTED: 'connected',
  ERROR: 'error',
  CLOSED: 'closed'
}

/**
 * SOCKS5 client implementation
 * Handles SOCKS5 protocol negotiation and connection establishment
 */
class Socks5Client extends EventEmitter {
  constructor (socket, options = {}) {
    super()

    if (!socket) {
      throw new InvalidArgumentError('socket is required')
    }

    this.socket = socket
    this.options = options
    this.state = STATES.INITIAL
    this.buffer = EMPTY_BUFFER
    this.onSocketData = this.onData.bind(this)
    this.onSocketError = this.onError.bind(this)
    this.onSocketClose = this.onClose.bind(this)

    // Authentication settings
    this.authMethods = []
    if (options.username && options.password) {
      this.authMethods.push(AUTH_METHODS.USERNAME_PASSWORD)
    }
    this.authMethods.push(AUTH_METHODS.NO_AUTH)

    // Socket event handlers

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Ensure the socket argument is a connected (or connecting) net.Socket/duplex stream before instantiating Socks5Client.
2. Add a guard at the call site so a failed upstream connection does not reach the constructor.
3. Run a type check or assertion that the socket is non-null and is a Duplex.

Example fix

// before
const client = new Socks5Client(maybeSocket)

// after
if (!maybeSocket) throw new Error('upstream socket unavailable')
const client = new Socks5Client(maybeSocket)

function makeSocks5Client(socket, options) {
  if (!socket || typeof socket.write !== 'function') {
    throw new Error('a writable socket is required')
  }
  return new Socks5Client(socket, options)
}

function isDuplexSocket(v) {
  return v != null && typeof v.write === 'function' && typeof v.on === 'function'
}

When it happens

Trigger: Constructing `new Socks5Client(null)`, `new Socks5Client(undefined)`, or `new Socks5Client()` (defaulting socket to undefined). Also when a socket variable is conditionally assigned and falls through to undefined before being passed in.

Common situations: Refactoring a proxy setup and forgetting to plumb the socket; a connection step that returns null on failure being passed straight into the client; copy-paste from a sample that omitted the socket argument.

Related errors

• UND_ERR_SOCKS5_ADDR_TYPE
• UND_ERR_INVALID_ARG
• SqliteCacheStore options must be an object
• UND_ERR_SOCKS5_VERSION
• UND_ERR_SOCKS5_AUTH_REJECTED

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