nats-io/nats-server · error

unrecognized PROXY protocol format

Error message

unrecognized PROXY protocol format

What it means

The first bytes on the connection match neither the PROXY v2 signature nor the 'PROXY ' v1 prefix, so the data is not PROXY protocol at all. The reader returns the consumed bytes so the caller can replay them into the next protocol layer instead of discarding them.

Source

Thrown at server/client_proxyproto.go:77

	// 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))
}

// Network implements net.Addr interface
func (p *proxyProtoAddr) Network() string {
	if p.srcIP.To4() != nil {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Disable proxy protocol on the listener if clients connect directly
2. Verify the peer actually speaks PROXY protocol v1 or v2
3. Check that an intermediary is not mangling or stripping the header

When it happens

Trigger: Thrown at server/client_proxyproto.go:77 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/4533c75812ce0355. Report an issue: GitHub.