XTLS/Xray-core · error

failed to read auth methods

Error message

failed to read auth methods

What it means

Thrown by ServerSession.auth5 (proxy/socks/protocol.go:106) during SOCKS5 method negotiation. The client's first message declares NMETHODS=n but the following read of n method bytes fails (EOF/timeout/reset), i.e. the client under-delivered its declared method list.

Source

Thrown at proxy/socks/protocol.go:106

			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)
		return "", errors.New("no matching auth method")
	}

	if err := writeSocks5AuthenticationResponse(writer, socks5Version, expectedAuth); err != nil {
		return "", errors.New("failed to write auth response").Base(err)
	}

	if expectedAuth == authPassword {
		username, password, err := ReadUsernamePassword(reader)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Verify the client sends exactly: 0x05, NMETHODS, then NMETHODS bytes, in one write when possible.
2. Check the base error: EOF = client closed mid-negotiation (client bug or probe); timeout = stalled peer.
3. Confirm no protocol mismatch (e.g. HTTPS or shadowsocks client pointed at the SOCKS inbound).

Example fix

// before: NMETHODS says 2 but only 1 method sent
conn.Write([]byte{0x05, 0x02, 0x00})

// after: NMETHODS matches the list (no-auth + username/password)
conn.Write([]byte{0x05, 0x02, 0x00, 0x02})

// Client-side: NMETHODS must equal the number of method bytes written
methods := []byte{0x00, 0x02}
req := append([]byte{0x05, byte(len(methods))}, methods...)
if _, err := conn.Write(req); err != nil {
    return err
}

if err != nil && strings.Contains(err.Error(), "failed to read auth methods") {
    logDebug("peer truncated SOCKS5 method negotiation")
    conn.Close()
}

When it happens

Trigger: Client writes 0x05 0x02 (version + NMETHODS=2) but sends only one method byte or disconnects; a scanner writing a 1-2 byte probe; a client that computed NMETHODS wrongly.

Common situations: Hand-rolled SOCKS5 clients with off-by-one NMETHODS; health checks probing the port with junk; middleboxes dropping the tail of small packets; TLS clients connecting to a plain SOCKS port (handshake bytes parse as garbage).

Related errors

• failed to read username and password for authentication
• failed to read request
• failed to read address
• socks 4 is not allowed when auth is required.
• insufficient header

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