XTLS/Xray-core · error

unsupported command: %v

Error message

unsupported command: %v

What it means

Returned by handshake4 (proxy/socks/protocol.go:97) when the SOCKS4 command byte is anything other than cmdTCPConnect (0x01). The server writes a socks4RequestRejected response and rejects the request; SOCKS4 BIND (0x02) is not implemented.

Source

Thrown at proxy/socks/protocol.go:97

		}
		address = net.ParseAddress(domain)
	}

	switch cmd {
	case cmdTCPConnect:
		request := &protocol.RequestHeader{
			Command: protocol.RequestCommandTCP,
			Address: address,
			Port:    port,
			Version: socks4Version,
		}
		if err := writeSocks4Response(writer, socks4RequestGranted, net.AnyIP, net.Port(0)); err != nil {
			return nil, err
		}
		return request, nil
	default:
		writeSocks4Response(writer, socks4RequestRejected, net.AnyIP, net.Port(0))
		return nil, errors.New("unsupported command: ", cmd)
	}
}

func (s *ServerSession) auth5(nMethod byte, reader io.Reader, writer io.Writer) (username string, err error) {
	buffer := buf.StackNew()
	defer buffer.Release()

	if _, err = buffer.ReadFullFrom(reader, int32(nMethod)); err != nil {
		return "", errors.New("failed to read auth methods").Base(err)
	}

	var expectedAuth byte = authNotRequired
	if s.config.AuthType == AuthType_PASSWORD {
		expectedAuth = authPassword
	}

	if !hasAuthMethod(expectedAuth, buffer.BytesRange(0, int32(nMethod))) {
		writeSocks5AuthenticationResponse(writer, socks5Version, authNoMatchingMethod)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Change the client to use CONNECT (0x01); SOCKS BIND is not supported by this server in any version (SOCKS5 returns 'TCP bind is not supported.' too).
2. If the application truly needs BIND, SOCKS proxying is the wrong tool: expose the service directly or use a port-forward inbound.
3. Verify the client is not corrupting the request framing (wrong byte offsets produce arbitrary command values).

// Client-side: only CONNECT is valid for SOCKS4
const socks4Connect = 0x01
if cmd != socks4Connect {
    return fmt.Errorf("SOCKS4 command 0x%02X unsupported; only CONNECT (0x01) is allowed", cmd)
}

if err != nil && strings.Contains(err.Error(), "unsupported command") {
    // tell the caller this operation needs a different transport
    return ErrNeedsDirectConnection
}

When it happens

Trigger: A SOCKS4 client issuing command 0x02 (BIND) or any value other than 0x01 in the second header byte; also garbage input where the byte happens to be the version byte of another protocol.

Common situations: Applications that require inbound connections (FTP data channels, legacy peer-to-peer) attempting SOCKS4 BIND; malformed probes.

Related errors

• TCP bind is not supported.
• unknown command {cmd}
• socks 4 is not allowed when auth is required.
• insufficient header
• failed to read domain for socks 4a

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/77f3c55ccd5600cd. Report an issue: GitHub.