jackc/pgx · error

unknown startup message code

Error message

unknown startup message code: %d

What it means

The first message from the client has a protocol code that does not correspond to any known startup message (startup, SSLRequest, CancelRequest, GSSEncRequest). The %d is the unrecognized code.

Solutions

1. Verify the client sends a valid protocol version code (e.g. 196608 for 3.0)
2. Check for SSLRequest (80877103) or CancelRequest (80877102) codes if applicable
3. Ensure no extra bytes precede the startup message
4. Use pgproto3 library functions to construct valid startup messages

When it happens

Trigger: Thrown at pgproto3/backend.go:165 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/393e0fbc500066cf. Report an issue: GitHub.

Appendix: source

Thrown at pgproto3/backend.go:165

		err = b.sslRequest.Decode(buf)
		if err != nil {
			return nil, err
		}
		return &b.sslRequest, nil
	case cancelRequestCode:
		err = b.cancelRequest.Decode(buf)
		if err != nil {
			return nil, err
		}
		return &b.cancelRequest, nil
	case gssEncReqNumber:
		err = b.gssEncRequest.Decode(buf)
		if err != nil {
			return nil, err
		}
		return &b.gssEncRequest, nil
	default:
		return nil, fmt.Errorf("unknown startup message code: %d", code)
	}
}

// Receive receives a message from the frontend. The returned message is only valid until the next call to Receive.
func (b *Backend) Receive() (FrontendMessage, error) {
	if !b.partialMsg {
		header, err := b.cr.Next(5)
		if err != nil {
			return nil, translateEOFtoErrUnexpectedEOF(err)
		}

		b.msgType = header[0]

		msgLength := int(int32(binary.BigEndian.Uint32(header[1:])))
		if msgLength < 4 {
			return nil, fmt.Errorf("invalid message length: %d", msgLength)
		}

View on GitHub (pinned to ec1a0befd2)