nats-io/nats-server · error

invalid PROXY protocol header

Error message

invalid PROXY protocol header

What it means

Sentinel for malformed PROXY protocol input on a client connection; wrapped with context such as 'v1 line too long' or 'invalid v1 format' when the v1 text header cannot be parsed. Fires while reading the PROXY header when the peer sends data that is not a valid PROXY v1 header.

Source

Thrown at server/client_proxyproto.go:74

	// Header sizes
	proxyProtoV2HeaderSize = 16 // Fixed header: 12 (sig) + 1 (ver/cmd) + 1 (fam/proto) + 2 (addr len)

	// Timeout for reading PROXY protocol header
	proxyProtoReadTimeout = 5 * time.Second
)

// PROXY protocol v1 constants
const (
	proxyProtoV1Prefix     = "PROXY "
	proxyProtoV1MaxLineLen = 107 // Maximum line length including CRLF
	proxyProtoV1TCP4       = "TCP4"
	proxyProtoV1TCP6       = "TCP6"
	proxyProtoV1Unknown    = "UNKNOWN"
)

var (
	// Errors
	errProxyProtoInvalid      = errors.New("invalid PROXY protocol header")
	errProxyProtoUnsupported  = errors.New("unsupported PROXY protocol feature")
	errProxyProtoTimeout      = errors.New("timeout reading PROXY protocol header")
	errProxyProtoUnrecognized = errors.New("unrecognized PROXY protocol format")
)

// proxyProtoAddr contains the address information extracted from PROXY protocol header
type proxyProtoAddr struct {
	srcIP   net.IP
	srcPort uint16
	dstIP   net.IP
	dstPort uint16
}

// String implements net.Addr interface
func (p *proxyProtoAddr) String() string {
	return net.JoinHostPort(p.srcIP.String(), fmt.Sprintf("%d", p.srcPort))
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Verify the peer actually sends PROXY protocol v1/v2 (HAProxy-style)
2. Do not enable proxy protocol on a listener that receives direct client connections
3. Check the v1 line is under 107 bytes and CRLF-terminated

When it happens

Trigger: Thrown at server/client_proxyproto.go:74 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/8cc204b98c031e24. Report an issue: GitHub.