Client: LibpqwalreceiverReceive

Official description

Waiting in WAL receiver to receive data from remote server

Earlier names: Client/LibPQWalReceiverReceive (PG 13-16)

Trigger mechanism

WAIT_EVENT_LIBPQWALRECEIVER_RECEIVE at src/backend/replication/libpqwalreceiver/libpqwalreceiver.c:876 is the grep-verified reporting path. The public identity/resource is mapped at src/backend/utils/activity/wait_event.c:283. The instrumented operation is: Waiting in WAL receiver to receive data from remote server. The frontend protocol path reports LibpqwalreceiverReceive immediately before a socket, TLS/GSS, or replication-client operation blocks. PostgreSQL is waiting for the remote side or network to progress.

Normal or trouble?

• Normal: Idle ClientRead sessions are normal connection-pool inventory.
• Investigate: Investigate active writes, handshakes, old idle-in-transaction sessions, connection exhaustion, or replication-client stalls.

Diagnostic SQL

SELECT pid, backend_type, usename, datname, application_name,
       state, now() - query_start AS query_age,
       now() - xact_start AS xact_age,
       wait_event_type, wait_event,
       pg_blocking_pids(pid) AS blocking_pids,
       left(query, 160) AS query
FROM pg_stat_activity
WHERE wait_event_type = 'Client'
  AND wait_event = 'LibpqwalreceiverReceive'
ORDER BY query_age DESC NULLS LAST;

SELECT wait_event, count(*) AS waiting_sessions,
       count(*) FILTER (WHERE state = 'active') AS active_waiters,
       max(now() - query_start) AS oldest_query
FROM pg_stat_activity
WHERE wait_event_type = 'Client'
GROUP BY wait_event
ORDER BY waiting_sessions DESC, wait_event;

SELECT a.pid, l.locktype, l.mode, l.granted, l.fastpath,
       d.datname, n.nspname, c.relname,
       l.page, l.tuple, l.virtualxid, l.transactionid,
       l.classid, l.objid, l.objsubid
FROM pg_stat_activity AS a
LEFT JOIN pg_locks AS l ON l.pid = a.pid
LEFT JOIN pg_database AS d ON d.oid = l.database
LEFT JOIN pg_class AS c
  ON c.oid = l.relation
 AND l.database = (
       SELECT oid FROM pg_database WHERE datname = current_database()
     )
LEFT JOIN pg_namespace AS n ON n.oid = c.relnamespace
WHERE a.wait_event_type = 'Client'
  AND a.wait_event = 'LibpqwalreceiverReceive'
ORDER BY a.pid, l.granted, l.locktype, l.mode;

Response

1. Check state and transaction age before counting the wait as load.
2. Correlate with the owning application, pool, and network path.
3. Fix consumer backpressure or pool policy rather than repeatedly terminating connections.

Source evidence

• PostgreSQL 16.15 · src/backend/replication/libpqwalreceiver/libpqwalreceiver.c:876 — WAIT_EVENT_LIBPQWALRECEIVER_RECEIVE
• PostgreSQL 16.15 · src/backend/utils/activity/wait_event.c:283 — LibPQWalReceiverReceive
• PostgreSQL 18.6 · src/backend/replication/libpqwalreceiver/libpqwalreceiver.c:258 — WAIT_EVENT_LIBPQWALRECEIVER_RECEIVE
• PostgreSQL 18.6 · src/backend/utils/activity/wait_event_names.txt:89 — LIBPQWALRECEIVER_RECEIVE

Related controls and signals

• GUCs: [guc:wal_buffers] · [guc:synchronous_commit] · [guc:max_connections] · [guc:idle_in_transaction_session_timeout]
• Metrics: [metric:waiting_sessions] · [metric:wait_event_share] · [metric:wal_bytes] · [metric:wal_write_time] · [metric:active_backends]