jackc/pgx · error

pipeline has unsynced requests

Error message

pipeline has unsynced requests

What it means

Pipeline.Close guard: the pipeline is being closed while it still has requests that were never followed by a Sync message, so their results were never read. To avoid leaving the connection in an ambiguous protocol state, pgx force-closes the underlying connection and returns this sentinel error.

Solutions

1. Always call SendPipelineSync and consume all results before closing the pipeline
2. Drain outstanding results via GetResults/Exec before Close
3. Treat the connection as unusable afterwards — pgx has already async-closed it

When it happens

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

Appendix: source

Thrown at pgconn/pgconn.go:2949

}

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

		return p.err
	}

	for p.state.ExpectedReadyForQuery() > 0 {
		results, err := p.getResults()
		if err != nil {
			p.err = err
			var pgErr *PgError
			if !errors.As(err, &pgErr) {
				p.conn.asyncClose()
				break
			}
		} else if results == nil {
			// getResults returns (nil, nil) when the request queue is exhausted but
			// ExpectedReadyForQuery is still > 0. This can happen when FATAL errors consume

View on GitHub (pinned to ec1a0befd2)