IPC: WalReceiverUpstreamCatchup
Waiting for upstream server WAL flush position to catch up to requested start point
PostgreSQL wait event dossier
ClassIPC
Event
WalReceiverUpstreamCatchup
VersionsPG 17-18
Evidence2 source location(s)
Official description
Waiting for upstream server WAL flush position to catch up to requested start point
| PG 13 | PG 14 | PG 15 | PG 16 | PG 17 | PG 18 |
|---|---|---|---|---|---|
| — | — | — | — | ✓ | ✓ |
Important
Patch-level availability: Observed in 17.11+ and 18.6+; it is absent from 17.10 and 18.4, so the major-only range is insufficient.
Trigger mechanism
WAIT_EVENT_WAL_RECEIVER_UPSTREAM_CATCHUP at src/backend/replication/walreceiver.c:398 is the grep-verified reporting path. The public identity/resource is mapped at src/backend/utils/activity/wait_event_names.txt:165. The instrumented operation is: Waiting for upstream server WAL flush position to catch up to requested start point. The WalReceiverUpstreamCatchup path has reached a process-coordination point and sleeps until a peer, worker, barrier, queue, or replication phase signals progress.
Normal or trouble?
- Normal: Brief rendezvous is normal when every participant continues to advance.
- Investigate: Investigate when the same phase persists across three samples, the expected peer is absent or blocked, or a queue and its dependants stop moving.
Diagnostic SQL
Sessions waiting on IPC/WalReceiverUpstreamCatchup
Current IPC cohort
Lock and relation context for these sessions
Response
- Identify the peer or phase named by the event.
- Inspect that participant’s wait, error, and progress state.
- Repair the stalled participant or upstream dependency instead of treating the waiter as the root cause.
Source evidence
- PostgreSQL 18.6 · src/backend/replication/walreceiver.c:398 —
WAIT_EVENT_WAL_RECEIVER_UPSTREAM_CATCHUP - PostgreSQL 18.6 · src/backend/utils/activity/wait_event_names.txt:165 —
WAL_RECEIVER_UPSTREAM_CATCHUP
Related controls and signals
- GUCs: [guc:wal_buffers] · [guc:synchronous_commit]
- Metrics: [metric:waiting_sessions] · [metric:wait_event_share] · [metric:wal_bytes] · [metric:wal_write_time]