max_wal_senders Too Low: Standby or Backup Fails

Scenario

A DBA attempts to add a second streaming standby to a primary PostgreSQL server. The new standby fails to connect with: FATAL: number of requested standby connections exceeds max_wal_senders. Investigation reveals max_wal_senders = 2. One slot is consumed by the existing standby, and a pg_basebackup attempt for the new standby consumed the second slot simultaneously. Adding a replication slot for the new standby makes the problem worse. The fix requires increasing max_wal_senders and restarting.

How to Identify

Conditions:

• Standby fails to start with: FATAL: number of requested standby connections exceeds max_wal_senders
• pg_basebackup exits with the same error message
• SELECT count(*) FROM pg_stat_replication equals max_wal_senders
• pg_replication_slots shows active slots each consuming a WAL sender
• wal_level is not replica or logical — also causes replication failure independently

Analysis Steps

-- Check current limits and wal_level (both require restart to change):
SHOW max_wal_senders;
SHOW wal_level;   -- must be 'replica' or 'logical'

-- Count active WAL sender processes:
SELECT count(*) AS active_wal_senders FROM pg_stat_replication;

-- View all active replication connections in detail:
SELECT pid, usename, application_name, client_addr,
       state, sent_lsn, write_lsn, flush_lsn, replay_lsn, sync_state
FROM pg_stat_replication;
-- Each row = one WAL sender slot consumed

-- Count replication slots (active ones also consume WAL senders):
SELECT slot_name, slot_type, active, active_pid
FROM pg_replication_slots;

-- Current headroom — how close are we to the limit?
SELECT
    current_setting('max_wal_senders')::int              AS max_wal_senders,
    (SELECT count(*) FROM pg_stat_replication)           AS active_senders,
    current_setting('max_wal_senders')::int -
    (SELECT count(*) FROM pg_stat_replication)           AS available_slots;

Pitfalls

• max_wal_senders requires a server restart — it cannot be changed with pg_reload_conf(). Plan for a maintenance window.
• pg_basebackup itself consumes a WAL sender slot for the entire duration of the backup. Size: max_wal_senders ≥ standbys + replication slots + basebackup headroom.
• If wal_level is not replica or logical, streaming replication fails regardless of max_wal_senders. Both parameters require a restart if changed.
• Replication slots count against max_wal_senders when their consumers are connected. A slot that is normally idle can suddenly claim a sender at any time.
• max_replication_slots is a separate parameter limiting total slot count. It also requires a restart and must be set alongside max_wal_senders.
• Setting max_wal_senders = 0 disables replication entirely and requires a restart to re-enable.

Resolution Approach

Increase max_wal_senders to accommodate: all current standbys + replication slots + headroom for pg_basebackup operations (recommend 2–3 extra slots). Verify wal_level = replica. Apply via ALTER SYSTEM and restart. No data loss results from this change.