# Activity: RecoveryWalStream

> Waiting in main loop of startup process for WAL to arrive, during streaming recovery
---

<div class="event-kicker">PostgreSQL wait event dossier</div>
<div class="event-identity">
  <span>Class<strong>Activity</strong></span>
  <span>Event<strong><code>RecoveryWalStream</code></strong></span>
  <span>Versions<strong>PG 13-18</strong></span>
  <span>Evidence<strong>2 source location(s)</strong></span>
</div>

## Official description {#official-description}

Waiting in main loop of startup process for WAL to arrive, during streaming recovery

| PG 13 | PG 14 | PG 15 | PG 16 | PG 17 | PG 18 |
| :---: | :---: | :---: | :---: | :---: | :---: |
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

## Trigger mechanism {#mechanism}

`WAIT_EVENT_RECOVERY_WAL_STREAM` at `src/backend/access/transam/xlogrecovery.c:4038` is the grep-verified reporting path. The public identity/resource is mapped at `src/backend/utils/activity/wait_event_names.txt:64`. The instrumented operation is: Waiting in main loop of startup process for WAL to arrive, during streaming recovery. The RecoveryWalStream background path reports this event around its latch wait when its main loop has no immediate work. A signal, timeout, or new work clears the sleep and the process loops again.

## Normal or trouble? {#normal-vs-trouble}

- <span class="severity-normal">**Normal:**</span> This is normally expected idleness for the matching background process.
- <span class="severity-watch">**Investigate:**</span> Investigate only when queued work or a shutdown/failover deadline is not advancing while the process remains here, or when the event appears on an unexpected backend type.

## Diagnostic SQL {#diagnostic-sql}

```sql {title="Sessions waiting on Activity/RecoveryWalStream"}
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 = 'Activity'
  AND wait_event = 'RecoveryWalStream'
ORDER BY query_age DESC NULLS LAST;
```

```sql {title="Current Activity cohort"}
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 = 'Activity'
GROUP BY wait_event
ORDER BY waiting_sessions DESC, wait_event;
```

```sql {title="Lock and relation context for these sessions"}
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 = 'Activity'
  AND a.wait_event = 'RecoveryWalStream'
ORDER BY a.pid, l.granted, l.locktype, l.mode;
```

## Response {#response}

1. Match the row to backend_type.
2. Inspect the process-specific backlog and last-progress timestamp.
3. Fix the missing work signal or stalled upstream phase; do not kill a normally idle worker.

## Source evidence {#source}

- [PostgreSQL 18.6 · src/backend/access/transam/xlogrecovery.c:4038](https://github.com/postgres/postgres/blob/REL_18_6/src/backend/access/transam/xlogrecovery.c#L4038) — `WAIT_EVENT_RECOVERY_WAL_STREAM`
- [PostgreSQL 18.6 · src/backend/utils/activity/wait_event_names.txt:64](https://github.com/postgres/postgres/blob/REL_18_6/src/backend/utils/activity/wait_event_names.txt#L64) — `RECOVERY_WAL_STREAM`

## Related controls and signals {#related}

- **GUCs:** [[guc:wal_buffers]](/guc/wal-buffers/) · [[guc:synchronous_commit]](/guc/synchronous-commit/)
- **Metrics:** [[metric:waiting_sessions]](/metric/waiting-sessions/) · [[metric:wait_event_share]](/metric/wait-event-share/) · [[metric:wal_bytes]](/metric/wal-bytes/) · [[metric:wal_write_time]](/metric/wal-write-time/)

---

Backlinks:

- [Activity](/activity/)