nats-io/nats-server · error

unsupported PROXY protocol feature

Error message

unsupported PROXY protocol feature

What it means

Wrapped with detail when a syntactically valid PROXY protocol header uses a feature this server does not implement — anything other than STREAM/TCP transport, or an unsupported address family (reported as 0x??). The peer's PROXY header content is at fault, not the server configuration.

Source

Thrown at server/client_proxyproto.go:75

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

// Network implements net.Addr interface

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Ensure the upstream load balancer proxies STREAM/TCP connections
2. Upgrade the load balancer to emit a supported address family (TCP4/TCP6)
3. Disable PROXY protocol on that listener if the sender cannot comply

When it happens

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