cloudflare/cloudflared · error

Failed to read auth methods: %v

Error message

Failed to read auth methods: %v

What it means

StandardAuthHandler.Handle reads the SOCKS5 client's authentication method list via readMethods; if the underlying read fails (connection closed, malformed method-count header), the failure is wrapped with this message. It signals the auth negotiation phase could not complete.

Source

Thrown at socks/auth_handler.go:50

// NewAuthHandler creates a default auth handler
func NewAuthHandler() AuthHandler {
	defaults := make(map[uint8]Authenticator)
	defaults[NoAuth] = NewNoAuthAuthenticator()
	return &StandardAuthHandler{
		authenticators: defaults,
	}
}

// Register adds/replaces an Authenticator to use when handling Authentication requests
func (h *StandardAuthHandler) Register(method uint8, a Authenticator) {
	h.authenticators[method] = a
}

// Handle gets the methods from the SOCKS5 client and authenticates with the first supported method
func (h *StandardAuthHandler) Handle(bufConn io.Reader, conn io.Writer) error {
	methods, err := readMethods(bufConn)
	if err != nil {
		return fmt.Errorf("Failed to read auth methods: %v", err)
	}

	// first supported method is used
	for _, method := range methods {
		authenticator := h.authenticators[method]
		if authenticator != nil {
			return authenticator.Handle(bufConn, conn)
		}
	}

	// failed to authenticate. No supported authentication type found
	conn.Write([]byte{socks5Version, noAcceptable})
	return fmt.Errorf("unknown authentication type")
}

// readMethods is used to read the number and type of methods
func readMethods(r io.Reader) ([]byte, error) {
	header := []byte{0}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Verify the client actually speaks SOCKS5 (version byte 0x05) before connecting to the proxy port.
2. Check client-side that the full method negotiation (count + method bytes) is written before awaiting a reply.
3. Retry the connection if it was a transient network issue.
4. Log the wrapped cause to distinguish EOF/reset from protocol garbage.

Example fix

// before
if err := authHandler.Handle(bufConn, conn); err != nil {
    return err
}
// after
if err := authHandler.Handle(bufConn, conn); err != nil {
    logger.Debug().Err(err).Msg("socks auth negotiation failed; client likely not socks5")
    return err
}

if err := h.authHandler.Handle(bufConn, conn); err != nil {
    logger.Debug().Err(err).Msg("socks handshake failed")
    // close conn; do not treat as server error
}

When it happens

Trigger: A SOCKS5 client disconnects or sends fewer bytes than the declared number of auth methods while the SOCKS server calls Handle.

Common situations: Non-SOCKS5 clients (health checkers, port scanners) hitting the SOCKS port; clients closing the connection immediately; network interruptions during handshake.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Failed to fetch resource
• unknown authentication type
• Unsupported auth version: %v
• User authentication failed
• Failed to get command version: %v

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