jackc/pgx · error

pipeline: : received unexpected message type %T

Error message

pipeline: %s: received unexpected message type %T

What it means

The pipeline received an unexpected message type while processing a specific step. The %s identifies which pipeline step failed. The pipeline is closed and the error recorded; no further pipeline steps can proceed.

Solutions

1. Check the step name and message type in the error
2. Verify each pipeline step sends valid protocol messages
3. Ensure Sync is issued at appropriate points
4. Test the same queries outside pipeline mode

When it happens

Trigger: Thrown at pgconn/pgconn.go:2934 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/83835967982c9a1f. Report an issue: GitHub.

Appendix: source

Thrown at pgconn/pgconn.go:2934

	for {
		msg, err := p.conn.receiveMessage()
		if err != nil {
			p.err = err
			p.conn.asyncClose()
			return nil, normalizeTimeoutError(p.ctx, err)
		}

		switch msg := msg.(type) {
		case *pgproto3.ParameterStatus, *pgproto3.NoticeResponse, *pgproto3.NotificationResponse:
			// Filter these message types out in pipeline mode. The normal processing is handled by PgConn.receiveMessage.
		default:
			return msg, nil
		}
	}
}

func (p *Pipeline) handleUnexpectedMessage(errStr string, msg pgproto3.BackendMessage) error {
	p.err = fmt.Errorf("pipeline: %s: received unexpected message type %T", errStr, msg)
	p.conn.asyncClose()
	return p.err
}

// Close closes the pipeline and returns the connection to normal mode.
func (p *Pipeline) Close() error {
	if p.closed {
		return p.err
	}

	p.closed = true

	if p.state.PendingSync() {
		p.conn.asyncClose()
		p.err = errors.New("pipeline has unsynced requests")
		p.conn.contextWatcher.Unwatch()
		p.conn.unlock()

View on GitHub (pinned to ec1a0befd2)