jackc/pgx · error

invalid length of startup packet

Error message

invalid length of startup packet: %d

What it means

The startup packet received by the backend (server-side) declared a length that is negative or too small to be a valid message. The %d shows the computed message size. The connection is rejected.

Solutions

1. If building a client, ensure the startup packet length is correctly encoded
2. Verify the length field accounts for the 4 length bytes themselves
3. Check for byte-order issues (must be big-endian)
4. Use pgproto3's StartupMessage.Encode to generate valid packets

When it happens

Trigger: Thrown at pgproto3/backend.go:129 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/feefdf6ebcf46d78. Report an issue: GitHub.

Appendix: source

Thrown at pgproto3/backend.go:129

}

// Untrace stops tracing.
func (b *Backend) Untrace() {
	b.tracer = nil
}

// ReceiveStartupMessage receives the initial connection message. This method is used of the normal Receive method
// because the initial connection message is "special" and does not include the message type as the first byte. This
// will return either a StartupMessage, SSLRequest, GSSEncRequest, or CancelRequest.
func (b *Backend) ReceiveStartupMessage() (FrontendMessage, error) {
	buf, err := b.cr.Next(4)
	if err != nil {
		return nil, err
	}
	msgSize := int(int32(binary.BigEndian.Uint32(buf)) - 4)

	if msgSize < minStartupPacketLen || msgSize > maxStartupPacketLen {
		return nil, fmt.Errorf("invalid length of startup packet: %d", msgSize)
	}

	buf, err = b.cr.Next(msgSize)
	if err != nil {
		return nil, translateEOFtoErrUnexpectedEOF(err)
	}

	code := binary.BigEndian.Uint32(buf)

	switch code {
	case ProtocolVersion30, ProtocolVersion32:
		err = b.startupMessage.Decode(buf)
		if err != nil {
			return nil, err
		}
		return &b.startupMessage, nil
	case sslRequestNumber:
		err = b.sslRequest.Decode(buf)

View on GitHub (pinned to ec1a0befd2)