nats-io/nats-server · error

timeout reading PROXY protocol header

Error message

timeout reading PROXY protocol header

What it means

The proxyProtoReadTimeout deadline (5 seconds) expired before the full PROXY protocol header arrived: the peer opened the connection but stalled mid-header. Returned unwrapped when io.ReadFull fails with a net.Error timeout.

Source

Thrown at server/client_proxyproto.go:76

	// 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 {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check network health/MTU between the PROXY sender and the server
2. Ensure the load balancer writes the header immediately after connect
3. Disable proxy protocol on the listener if the sender cannot be fixed

When it happens

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

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

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