XTLS/Xray-core · error

invalid username or password

Error message

invalid username or password

What it means

Thrown in auth5 (proxy/socks/protocol.go:131) when the RFC 1929 message parsed correctly but config.HasAccount(username, password) returned false. The server responds 0x01 0xFF (auth failure) and closes; the credentials simply do not match any account on the inbound.

Source

Thrown at proxy/socks/protocol.go:131

	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)
		if err != nil {
			return "", errors.New("failed to read username and password for authentication").Base(err)
		}

		if !s.config.HasAccount(username, password) {
			writeSocks5AuthenticationResponse(writer, 0x01, 0xFF)
			return "", errors.New("invalid username or password")
		}

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

	return "", nil
}

func (s *ServerSession) handshake5(nMethod byte, reader io.Reader, writer net.Conn) (*protocol.RequestHeader, *TempUDPConn, error) {
	var (
		username string
		err      error
	)
	if username, err = s.auth5(nMethod, reader, writer); err != nil {
		return nil, nil, err

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Compare the exact username/password the client sends against the inbound's accounts entry in the Xray config JSON.
2. Watch for invisible characters: trailing spaces, CR/LF, or JSON escaping issues in the credentials.
3. If credentials were rotated, update both the server accounts list and every client, then restart/reload.
4. Enable access logging on the inbound to confirm which username is actually arriving.

Example fix

// before: mismatch between client and server credentials
// client: user=alice pw=secret1
{ "accounts": [{ "user": "alice", "pass": "secret2" }] }

// after: aligned
{ "accounts": [{ "user": "alice", "pass": "secret1" }] }

// Server-side: verify an account exists before enabling password auth
if len(inbound.Settings.Accounts) == 0 && inbound.Settings.Auth == "password" {
    return fmt.Errorf("password auth enabled but no accounts configured")
}
// Client-side: assert credentials are set before dialing
if serverAuthRequired && (user == "" || pass == "") {
    return fmt.Errorf("credentials missing for authenticated SOCKS5 server")
}

if err != nil && strings.Contains(err.Error(), "invalid username or password") {
    // surface a clear message; do not retry blindly with the same credentials
    return errors.New("SOCKS5 credentials rejected: check inbound accounts list")
}

When it happens

Trigger: Client authenticates with a username/password pair that is not in the inbound's accounts list, or the account was removed/reloaded with different credentials; also possible hash/copy mistakes when pasting secrets.

Common situations: Typo'd password in client config; rotated credentials updated on one side only; environments where the inbound config was regenerated; trailing whitespace/newlines from copy-paste in JSON.

Related errors

• no matching auth method
• socks 4 is not allowed when auth is required.
• failed to read auth methods
• failed to read username and password for authentication
• UDP is not enabled.

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