cloudflare/cloudflared · error

Unsupported command version: %v

Error message

Unsupported command version: %v

What it means

socks.NewRequest reads the first 3 bytes of a SOCKS5 connection and checks that the version byte is socks5Version (0x05). If the client sends a different protocol version byte, the library refuses to parse the request and returns this error. It guards against speaking to non-SOCKS5 or SOCKS4 clients on a SOCKS5 listener.

Source

Thrown at socks/request.go:84

	// Requested command
	Command uint8
	// AddrSpec of the destination
	DestAddr *AddrSpec
	// reading from the connection
	bufConn io.Reader
}

// NewRequest creates a new request from the connection data stream
func NewRequest(bufConn io.Reader) (*Request, error) {
	// Read the version byte
	header := []byte{0, 0, 0}
	if _, err := io.ReadAtLeast(bufConn, header, 3); err != nil {
		return nil, fmt.Errorf("Failed to get command version: %v", err)
	}

	// ensure compatibility
	if header[0] != socks5Version {
		return nil, fmt.Errorf("Unsupported command version: %v", header[0])
	}

	// Read in the destination address
	dest, err := readAddrSpec(bufConn)
	if err != nil {
		return nil, err
	}

	return &Request{
		Version:  socks5Version,
		Command:  header[1],
		DestAddr: dest,
		bufConn:  bufConn,
	}, nil
}

func sendReply(w io.Writer, resp uint8, addr *AddrSpec) error {
	var addrType uint8

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Reconfigure the client to use SOCKS5 (version 0x05) protocol
2. Verify nothing else (HTTP proxy, TLS terminator, health checks) is pointing at the SOCKS listener port
3. If you must accept legacy clients, read the version byte yourself and reject/pre-process before calling NewRequest
4. Check that no proxy chaining step strips or rewrites the greeting bytes

Example fix

// before: client configured with SOCKS4
proxy.setScheme("socks4")

// after
proxy.setScheme("socks5") // sends version byte 0x05

// client side: ensure the first greeting byte is SOCKS5 (0x05)
if ver := 0x05; ver != socks5Version {
    return fmt.Errorf("client must speak SOCKS5, got version %d", ver)
}

func isSOCKS5Conn(firstByte byte) bool { return firstByte == 0x05 }

if err := serveSOCKS(conn); err != nil {
    if strings.Contains(err.Error(), "Unsupported command version") {
        log.Warn().Msg("non-SOCKS5 client on SOCKS port; check client proxy scheme")
    }
}

When it happens

Trigger: Calling socks.NewRequest (directly or via RequestHandler.Serve) on a connection whose first byte is not 0x05 — e.g. a SOCKS4/4a client, plain HTTP traffic, TLS traffic, or garbage bytes hitting the SOCKS port.

Common situations: A proxy client misconfigured to use SOCKS4 instead of SOCKS5; an HTTP proxy client pointed at a SOCKS5 port; a port scanner or load-balancer health check probing the listener; a TLS-wrapped client connecting to a plaintext SOCKS port.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Failed to read auth methods: %v
• Failed to get command version: %v
• Failed to format address: %v
• Unrecognized address type
• Failed to send reply: %v

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/23edf31a4e8d4bcb. Report an issue: GitHub.