cloudflare/cloudflared · error

Unsupported SOCKS version: %v

Error message

Unsupported SOCKS version: %v

What it means

SOCKS connection handler Serve reads the first byte of the connection and requires it to be socks5Version (0x05). Any other value means the client is not speaking SOCKS5, so Serve returns this error before auth negotiation begins.

Source

Thrown at socks/connection_handler.go:42

	return &StandardConnectionHandler{
		requestHandler: requestHandler,
		authHandler:    NewAuthHandler(),
	}
}

// Serve process new connection created after calling `Accept()` in the standard library
func (h *StandardConnectionHandler) Serve(c io.ReadWriter) error {
	bufConn := bufio.NewReader(c)

	// read the version byte
	version := []byte{0}
	if _, err := bufConn.Read(version); err != nil {
		return err
	}

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

	// handle auth
	if err := h.authHandler.Handle(bufConn, c); err != nil {
		return err
	}

	// process command/request
	req, err := NewRequest(bufConn)
	if err != nil {
		return err
	}

	return h.requestHandler.Handle(req, c)
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Configure the client to use SOCKS5 (not HTTP or SOCKS4) for the proxy port.
2. Confirm the port in client config matches the cloudflared SOCKS listener.
3. Filter or ignore noise from scanners/probes hitting the port.
4. Log the offending version byte to identify the client type.

Example fix

// before
const proxy = "http://localhost:1080"
// after
const proxy = "socks5://localhost:1080"

// client: ensure socks5 scheme
u, _ := url.Parse(proxyURL)
if u.Scheme != "socks5" && u.Scheme != "socks5h" { return errors.New("proxy must be socks5") }

if err := h.Serve(ctx, conn); err != nil {
    if strings.Contains(err.Error(), "Unsupported SOCKS version") {
        logger.Debug().Msg("non-SOCKS5 client connected to socks port")
    }
    return err
}

When it happens

Trigger: A client sends an HTTP request, TLS ClientHello, or raw bytes to the SOCKS port; the first byte differs from 0x05.

Common situations: Pointing a browser at the port with plain HTTP proxy settings vs SOCKS5; port scanners or monitoring probes; client configured for SOCKS4.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• unknown protocol %v
• invalid datagram type expected
• %s has unknown TLS settings
• Received unknown connection type: %s
• unknown protocol %s, %s

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