cloudflare/cloudflared · error

Failed to read auth methods

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.

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

• Connect to denied
• Connect to denied due to iprule
• Connect to failed
• failed to create tunnel
• Failed to fetch resource

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

Appendix: 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)